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INTRODUCTION 


This manual describes the programming features of the UNIX system. It provides nei- 
ther a general overview of the UNIX system nor details of the implementation of the 
system. 

Not all commands, features, and facilities described in this manual are available in 
every UNIX system. Some of the features require additional utilities which may not 
exist on your system. 

This manual is divided into four sections, some containing interfiled subclasses: 

2. System Calls. 

3. Subroutines: 

3C. C Programming Language Libraries 
3S. Standard I/O Library Routines 
3M. Mathematical Library Routines 
3X. Specialized Libraries 
3F. FORTRAN Programming Libraries 

4. File Formats. 

5. Miscellaneous Facilities. 

Section 2 (.System Calls) describes the entries into the UNIX system kernel, including 
the C language interface. 

Section 3 ( Subroutines ) describes the available subroutines. Their binary versions 
reside in various system libraries in the directories /lib and /usr/lib. See intro ( 3) for 
descriptions of these libraries and the files in which they are stored. 

Section 4 (File Formats) documents the structure of particular kinds of files; for exam- 
ple, the format of the output of the link editor is given in a. out (4). Excluded are files 
used by only one command (for example, the assembler’s intermediate files). In gen- 
eral, the C language struct declarations corresponding to these formats can be found in 
the directories /usr/include and /usr/include/sys. 

Section 5 (Miscellaneous Facilities) contains a variety of things. Included are descrip- 
tions of character sets, macro packages, etc. 

References with numbers other than those above mean that the utility is contained in 
the appropriate section of another manual. References with (1) following the command 
generally mean that the utility is contained in the AT&T 3B2 Computer System User 
Reference Manual. Those followed by (1M), (7), or (8) are contained in the AT&T 
3B2 Computer System Administration Utilities Guide. 

Each section consists of a number of independent entries of a page or so each. The 
name of the entry appears in the upper corners of its pages. Entries within each section 
are alphabetized, with the exception of the introductory entry that begins each section 
(also Section 3 is in alphabetical order by suffixes). Some entries may describe several 
routines, commands, etc. In such cases, the entry appears only once, alphabetized 
under its “major” name. 

All entries are based on a common format, not all of whose parts always appear: 

The NAME part gives the name(s) of the entry and briefly states its purpose. 

The SYNOPSIS part summarizes the use of the program being described. A few 
conventions are used, particularly in Section 2 (System Calls)-. 

Boldface strings are literals and are to be typed just as they appear. 

Italic strings usually represent substitutable argument prototypes and program 
names found elsewhere in the manual (they are underlined in the typed ver- 
sion of the entries). 
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Introduction 


Square brackets [] around an argument prototype indicate that the argument 
is optional. When an argument prototype is given as “name” or “file”, it 
always refers to a file name. 

Ellipses ... are used to show that the previous argument prototype may be 
repeated. 

A final convention is used by the commands themselves. An argument begin- 
ning with a minus — , plus +, or equal sign = is often taken to be some sort of 
flag argument, even if it appears in a position where a file name could appear. 
Therefore, it is unwise to have files whose names begin with — , +, or =. 

The DESCRIPTION part discusses the subject at hand. 

The EXAMPLE(S) part gives example(s) of usage, where appropriate. 

The FILES part gives the file names that are built into the program. 

The SEE ALSO part gives pointers to related information. 

The DIAGNOSTICS part discusses the diagnostic indications that may be produced. 
Messages that are intended to be self-explanatory are not listed. 

The WARNINGS part points out potential pitfalls. 

The BUGS part gives known bugs and sometimes deficiencies. Occasionally, the 
suggested fix is also described. 

A table of contents and a permutted index derived from that table precede Section 2. 
On each index line, the title of the entry to which that line refers is followed by the 
appropriate section number in parentheses. This is important because there is consider- 
able duplication of names among the sections, arising principally from commands that 
exist only to exercise a particular system call. 

A Permuted Index follows the Introduction and Table of Contents. The Permuted 
Index is used by searching the middle column for a key word or phrase. The right 
column will then contain the name of the manual page that contains that command. 
The left column contains additional useful information about the command. 
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TABLE OF CONTENTS 


2. System Calls 

intro introduction to system calls and error numbers 

access determine accessibility of a file 

acct enable or disable process accounting 

alarm set a process alarm clock 

brk change data segment space allocation 

chdir change working directory 

chmod change mode of file 

chown change owner and group of a file 

chroot change root directory 

close close a file descriptor 

creat create a new file or rewrite an existing one 

dup duplicate an open file descriptor 

exec execute a file 

exit terminate process 

fcntl file control 

fork create a new process 

getpid get process, process group, and parent process IDs 

getuid get real user, effective user, real group, and effective group IDs 

ioctl control device 

kill send a signal to a process or a group of processes 

link link to a file 

lseek move read/write file pointer 

mknod make a directory, or a special or ordinary file 

mount mount a file system 

msgctl message control operations 

msgget get message queue 

msgop message operations 

nice change priority of a process 

open open for reading or writing 

pause suspend process until signal 

pipe create an interprocess channel 

plock lock process, text, or data in memory 

profil execution time profile 

ptrace process trace 

read read from file 

semctl semaphore control operations 

semget get set of semaphores 

semop semaphore operations 

setpgrp set process group ID 

setuid set user and group IDs 

shmctl shared memory control operations 

shmget get shared memory segment 

shmop shared memory operations 

signal specify what to do upon receipt of a signal 

stat get file status 

stime set time 

sync update super block 

sys3b \\ machine specific function 

time get time 

times get process and child process times 

uadmin administrative control 

ulimit get and set user limits 

umask set and get file creation mask 

umount unmount a file system 
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uname get name of current UNIX system 

unlink remove directory entry 

ustat get file system statistics 

utime set file access and modification times 

wait wait for child process to stop or terminate 

write write on a file 


3. Subroutines 


intro introduction to subroutines and libraries 

C PROGRAMMING LANGUAGE UTILITIES 

a641 convert between long integer and base-64 ASCII string 

abort generate an IOT fault 

abs return integer absolute value 

bsearch binary search a sorted table 

clock report CPU time used 

conv translate characters 

crypt generate hashing encryption 

ctermid generate file name for terminal 

ctime convert date and time to string 

ctype classify characters 

cuserid get character login name of the user 

dial establish an outgoing terminal line connection 

drand48 generate uniformly distributed pseudo-random numbers 

ecvt convert floating-point number to string 

end last locations in program 

fclose close or flush a stream 

ferror stream status inquiries 

fopen open a stream 

fread binary input/output 

frexp manipulate parts of floating-point numbers 

fseek reposition a file pointer in a stream 

ftw walk a file tree 

getc get character or word from a stream 

getcwd get path-name of current working directory 

getenv return value for environment name 

getgrent get group file entry 

getlogin get login name 

getopt get option letter from argument vector 

getpass read a password 

getpw get name from UID 

getpwent get password file entry 

gets get a string from a stream 

getut access utmp file entry 

hsearch manage hash search tables 

13tol convert between 3-byte integers and long integers 

lockf record locking on files 

lsearch linear search and update 

malloc main memory allocator 

memory memory operations 

mktemp make a unique file name 

monitor prepare execution profile 

nlist get entries from name list 

perror system error messages 

popen initiate pipe to/from a process 

printf print formatted output 

putc put character or word on a stream 

putenv change or add value to environment 
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putpwent write password file entry 

puts put a string on a stream 

qsort quicker sort 

rand simple random-number generator 

scanf convert formatted input 

setbuf assign buffering to a stream 

setjmp non-local goto 

sleep suspend execution for interval 

ssignal software signals 

stdio standard buffered input/output package 

stdipc standard interprocess communication package 

string string operations 

strtod convert string to double-precision number 

strtol convert string to integer 

swab swap bytes 

system issue a shell command 

tmpfile create a temporary file 

tmpnam create a name for a temporary file 

tsearch manage binary search trees 

ttyname find name of a terminal 

ttyslot find the slot in the utmp file of the current user 

ungetc push character back into input stream 

vprintf print formatted output of a varargs argument list 

MATH LIBRARIES 

bessel Bessel functions 

erf error function and complementary error function 

exp exponential, logarithm, power, square root functions 

floor floor, ceiling, remainder, absolute value functions 

gamma log gamma function 

hypot Euclidean distance function 

matherr error-handling function 

sinh hyperbolic functions 

trig trigonometric functions 

SPECIALIZED LIBRARIES 

assert verify program assertion 

curses CRT screen handling and optimization package 

ldahread read the archive header of a member of an archive file 

Idclose close a common object file 

ldfhread read the file header of a common object file 

ldgetname .... retrieve symbol name for common object file symbol table entry 

ldlread manipulate line number entries of a common object file function 

ldlseek seek to line number entries of a section of a common object file 

ldohseek seek to the optional file header of a common object file 

ldopen open a common object file for reading 

ldrseek seek to relocation entries of a section of a common object file 

ldshread read an indexed/named section header of a common object file 

ldsseek seek to an indexed/named section of a common object file 

ldtbindex . . . compute the index of a symbol table entry of a common object file 

ldtbread read an indexed symbol table entry of a common object file 

ldtbseek seek to the symbol table of a common object file 

logname return login name of user 

malloc fast main memory allocator 

plot graphics interface subroutines 

regcmp compile and execute regular expression 

sputl access long integer data in a machine-independent fashion 

vprintf print formatted output of a varargs argument list 
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FORTRAN PROGRAMMING LIBRARIES 

abort terminate Fortran program 

abs Fortran absolute value 

acos Fortran arccosine intrinsic function 

aimag Fortran imaginary part of complex argument 

aint Fortran integer part intrinsic function 

asin Fortran arcsine intrinsic function 

atan Fortran arctangent intrinsic function 

atan2 Fortran arctangent intrinsic function 

bool Fortran bitwise Boolean functions 

conjg Fortran complex conjugate intrinsic function 

cos Fortran cosine intrinsic function 

cosh Fortran hyperbolic cosine intrinsic function 

dim positive difference intrinsic functions 

dprod double precision product intrinsic function 

exp Fortran exponential intrinsic function 

ftype explicit Fortran type conversion 

getarg return Fortran command-line argument 

getenv return Fortran environment variable 

iargc return the number of command line arguments 

index return location of Fortran substring 

len return length of Fortran string 

log Fortran natural logarithm intrinsic function 

log 10 Fortran common logarithm intrinsic function 

max Fortran maximum-value functions 

mclock return Fortran time accounting 

mil bit field manipulation intrinsic function and subroutines 

min Fortran minimum-value functions 

mod Fortran remaindering intrinsic functions 

rand random-number generator 

round . . Fortran nearest integer functions 

sign Fortran transfer-of-sign intrinsic function 

signal specify Fortran action on receipt of a system signal 

sin Fortran sine intrinsic function 

sinh Fortran hyperbolic sine intrinsic function 

sqrt Fortran square root intrinsic function 

strcmp string comparison intrinsic functions 

system issue a shell command from Fortran 

tan Fortran tangent intrinsic function 

tanh Fortran hyperbolic tangent intrinsic function 

4. File Formats 

intro introduction to file formats 

a. out common assembler and link editor output 

ar common archive file format 

checklist list of file systems processed by fsck 

core format of core image file 

cpio format of cpio archive 

dir format of directories 

filehdr file header for common object files 

fs format of system volume 

fspec format specification in text files 

gettydefs speed and terminal settings used by getty 

gps graphical primitive string, format of graphical files 

group group file 

inittab script for the init process 

inode format of an i-node 
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issue issue identification file 

ldfcn common object file access routines 

linenum line number entries in a common object file 

master master configuration database 

mnttab mounted file system table 

passwd password file 

plot graphics interface 

pnch file format for card images 

profile system-wide user profile 

reloc relocation information for a common object file 

sccsfile format of SCCS file 

scnhdr section header for a common object file 

syms common object file symbol table format 

system system configuration information table 

term format of compiled term file. 

terminfo terminal capability data base 

timezone set default system time zone 

utmp utmp and wtmp entry formats 


5. Miscellaneous Facilities 


intro introduction to miscellany 

ascii map of ASCII character set 

environ user environment 

fcntl file control options 

math math functions and constants 

prof profile within a function 

regexp regular expression compile and match routines 

stat data returned by stat system call 

term conventional names for terminals 

types primitive system data types 

values machine-dependent values 

varargs handle variable argument list 
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PERMUTED INDEX 


13tol, ltol3: convert between 
long integer and base-64/ 

program. 
Fortran absolute value. 

value. 

abs: return integer 
dabs, cabs, zabs: Fortran 
/floor, ceiling, remainder, 
utime: set file 
accessibility of a file. 

sputl, sgetl: 
ldfcn: common object file 
/setutent, endutent, utmpname: 

access: determine 
enable or disable process 
mclock: return Fortran time 
process accounting, 
sin, cos, tan, asin, 
intrinsic function, 
putenv: change or 
uadmin: 

imaginary part of complex/ 
part intrinsic function, 
alarm: set a process 
clock. 

change data segment space 
realloc, calloc: main memory 
mallinfo: fast main memory 
natural logarithm/ log, 
logarithm intrinsic/ log 10, 
Fortran/ max, maxO, 
max, maxO, amaxO, maxi, 
Fortran/ min, minO, 
min, minO, aminO, mini, 
remaindering intrinsic/ mod, 
rshift: Fortran bitwise/ 
Fortran nearest integer/ 
format, 
acos, dacos: Fortran 
cpio: format of cpio 
ar: common 
header of a member of an 
an archive/ ldahread: read the 
asin, dasin: Fortran 
atan2, datan2: Fortran 
atan, datan: Fortran 
imaginary part of complex 
return Fortran command-line 
varargs: handle variable 
formatted output of a varargs 
formatted output of a varargs 
getopt: get option letter from 
the number of command line 
ascii: map of 
set. 

long integer and base-64 
and/ ctime, localtime, gmtime, 
trigonometric/ sin, cos, tan, 
intrinsic function, 
output, a.out: common 


3-byte integers and long/ . . 
a641, 164a: convert between 
abort: generate an IOT fault, 
abort: terminate Fortran . . . 
abs, iabs, dabs, cabs, zabs: . . 
abs: return integer absolute 

absolute value 

absolute value, abs, iabs, . . 
absolute value functions. . . 
access and modification times. 

access: determine 

access long integer data in a/ 

access routines 

access utmp file entry. . . . 

accessibility of a file 

accounting, acct: 

accounting 

acct: enable or disable . . . 

acos, atan, atan2:/ 

acos, dacos: Fortran arccosine 
add value to environment. . . 
administrative control. . . . 
aimag, dimag: Fortran . . . 
aint, dint: Fortran integer . . 

alarm clock 

alarm: set a process alarm . . 
allocation, brk, sbrk: .... 
allocator, malloc, free, . . . 
allocator, /calloc, mallopt, . . 
alog, dlog, clog: Fortran . . . 
aloglO, dlog 10: Fortran common 
amaxO, maxi, amaxl, dmaxl: 
amaxl, dmaxl: Fortran/ . . 
aminO, mini, aminl, dminl: . 
aminl, dminl: Fortran/ . . . 
amod, dmod: Fortran .... 
and, or, xor, not, lshift, . . . 
anint, dnint, nint, idnint: . . 
ar: common archive file ... 
arccosine intrinsic function. 

archive 

archive file format 

archive file, /the archive . . 
archive header of a member of 
arcsine intrinsic function. . . 
arctangent intrinsic function. . 
arctangent intrinsic function. . 
argument, /dimag: Fortran 

argument, getarg: 

argument list 

argument list, /print .... 
argument list, /print .... 

argument vector 

arguments, iargc: return . . 

ASCII character set 

ascii: map of ASCII character 
ASCII string, /convert between 
asctime, tzset: convert date 
asin, acos, atan, atan2: . . . 
asin, dasin: Fortran arcsine 
assembler and link editor . . 


13tol(3C) 

a641(3C) 

abort(3C) 

abort (3 F) 

abs(3F) 

abs(3C) 

abs(3C) 

abs(3F) 

floor (3 M) 

utime(2) 

access (2) 

sputl (3X) 

ldfcn (4) 

getut(3C) 

access (2) 

acct (2) 

mclock (3 F) 

acct (2) 

trig(3M) 

acos (3 F) 

putenv(3C) 

uadmin(2) 

aimag(3F) 

aint(3F) 

alarm (2) 

alarm (2) 

brk (2) 

malloc(3C) 

malloc(3X) 

log(3F) 

log 1 0(3F) 

max(3F) 

max(3F) 

min(3F) 

min(3F) 

mod(3F) 

bool (3 F) 

round (3 F) 

ar(4) 

acos (3 F) 

cpio (4) 

ar(4) 

ldahread (3X) 

ldahread (3X) 

asin (3 F) 

atan2(3F) 

atan (3 F) 

aimag(3F) 

getarg(3F) 

varargs (5) 

vprintf(3S) 

vprintf(3X) 

getopt (3C) 

iargc (3 F) 

ascii(5) 

ascii (5) 

a641(3C) 

ctime(3C) 

trig(3M) 

asin(3F) 

a.out (4) 
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assertion, 
assert: verify program 
setbuf, setvbuf: 
sin, cos, tan, asin, acos, 
arctangent intrinsic/ 
arctangent intrinsic/ 
cos, tan, asin, acos, atan, 
double-precision/ strtod, 
integer, strtol, atol, 
integer, strtol, 
ungetc: push character 
terminal capability data 
between long integer and 
jO, jl, jn, yO, yl, yn: 
fread, fwrite: 
bsearch: 

tfind, tdelete, twalk: manage 
btest, ibset, ibclr, mvbits: 
/not, Ishift, rshift: Fortran 
sync: update super 
rshift: Fortran bitwise 
space allocation, 
sorted table, 
/functions and subroutines., 
stdio: standard 
setbuf, setvbuf: assign 
swab: swap 
value, abs, iabs, dabs, 
data returned by stat system 
malloc, free, realloc, 
fast/ malloc, free, realloc, 
intro: introduction to system 
terminfo: terminal 
pnch: file format for 
function, cos, dcos, 
ceiling, remainder,/ floor, 
/ceil, fmod, fabs: floor, 
intrinsic/ exp, dexp, 
pipe: create an interprocess 
/dble, cmplx, dcmplx, ichar, 
stream, ungetc: push 
user, cuserid: get 
/getchar, fgetc, getw: get 
/putchar, fputc, putw: put 
ascii: map of ASCII 
_tolower, toascii: translate 
iscntrl, isascii: classify 
directory, 
systems processed by fsck. 
times: get process and 
terminate, wait: wait for 

of a file. 

isgraph, iscntrl, isascii: 
status/ ferror, feof, 
alarm: set a process alarm 

logarithm/ log, alog, dlog, 
ldclose, ldaclose: 

close: 
descriptor, 
fclose, fflush: 
/real, float, sngl, dble, 


assert: verify program assert(3X) 

assertion assert (3X) 

assign buffering to a stream setbuf(3S) 

atan, atan2: trigonometric/ trig (3 M) 

atan, datan: Fortran atan (3 F) 

atan2, datan2: Fortran atan2(3F) 

atan2: trigonometric/ sin, trig(3M) 

atof: convert string to strtod (3C) 

atoi: convert string to strtol (3C) 

atol, atoi: convert string to strtol (3C) 

back into input stream ungetc(3S) 

base, terminfo: terminfo(4) 

base-64 ASCII string, /convert a641(3C) 

Bessel functions bessel(3M) 

binary input/output fread (3S) 

binary search a sorted table bsearch (3C) 

binary search trees, tsearch, tsearch(3C) 

bit. /and subroutines., mil(3F) 

bitwise Boolean functions bool (3 F) 

block sync (2) 

Boolean functions. /Ishift, bool (3 F) 

brk, sbrk: change data segment brk(2) 

bsearch: binary search a bsearch (3C) 

btest, ibset, ibclr, mvbits:/ mil(3F) 

buffered input/output package stdio(3S) 

buffering to a stream setbuf(3S) 

bytes swab(3C) 

cabs, zabs: Fortran absolute abs(3F) 

call, stat: stat (5) 

calloc: main memory allocator malloc(3C) 

calloc, mallopt, mallinfo: malloc(3X) 

calls and error numbers intro(2) 

capability data base terminfo(4) 

card images pnch (4) 

ccos: Fortran cosine intrinsic cos(3F) 

ceil, fmod, fabs: floor, floor (3 M) 

ceiling, remainder, absolute/ floor (3 M) 

cexp: Fortran exponential exp(3F) 

channel pipe(2) 

char: explicit Fortran type/ ftype(3F) 

character back into input ungetc(3S) 

character login name of the cuserid (3S) 

character or word from a / getc(3S) 

character or word on a stream putc(3S) 

character set ascii (5) 

characters, / toupper, conv(3C) 

characters, /isprint, isgraph, ctype(3C) 

chdir: change working chdir(2) 

checklist: list of file checklist (4) 

child process times times (2) 

child process to stop or wait (2) 

chmod: change mode of file chmod(2) 

chown: change owner and group chown(2) 

chroot: change root directory chroot(2) 

classify characters, /isprint ctype(3C) 

clearerr, fileno: stream ferror (3S) 

clock alarm (2) 

clock: report CPU time used clock(3C) 

clog: Fortran natural log(3F) 

close a common object file ldclose (3X) 

close a file descriptor. close(2) 

close: close a file close (2) 

close or flush a stream fclose(3S) 

cmplx, dcmplx, ichar, char:/ ftype(3F) 
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system: issue a shell 
iargc: return the number of 
system: issue a shell 
getarg: return Fortran 
ar: 

editor output, a.out: 
log 10, aloglO, dloglO: Fortran 
routines, ldfcn: 
ldopen, ldaopen: open a 
/line number entries of a 
ldclose, Idaclose: close a 
read the file header of a 
entries of a section of a 
the optional file header of a 
/entries of a section of a 
/section header of a 
an indexed/named section of a 
of a symbol table entry of a 
symbol table entry of a 
seek to the symbol table of a 
line number entries in a 
relocation information for a 
scnhdr: section header for a 
/retrieve symbol name for 
table format, syms: 
filehdr: file header for 
ftok: standard interprocess 
lge, Igt, lie, lit: string 
expression, regcmp, regex: 
regexp: regular expression 
term: format of 
erf, erfc: error function and 
Fortran imaginary part of 
conjg, dconjg: Fortran 
table entry of a / ldtbindex: 

master: master 
table, system: system 
conjugate intrinsic function, 
conjg, dconjg: Fortran complex 
an out-going terminal line 
math: math functions and 
ioctl: 
fcntl: file 
msgctl: message 
semctl: semaphore 
shmctl: shared memory 
fcntl: file 
uadmin: administrative 
terminals, term: 
char: explicit Fortran type 
integers and/ 13tol, ltol3: 
and base-64 ASCII/ a641, 164a: 
/gmtime, asctime, tzset: 
to string, ecvt, fcvt, gcvt: 
scanf, fscanf, sscanf: 
strtod, atof: 
strtol, atol, atoi: 

file. 

core: format of 
cosine intrinsic function. 
atan2: trigonometric/ sin, 
hyperbolic cosine intrinsic/ 
functions, sinh, 
cos, dcos, ccos: Fortran 


command from Fortran. . . 
command line arguments. . 

command 

command-line argument, 
common archive file format, 
common assembler and link 
common logarithm intrinsic/ 
common object file access 
common object file for/ . . 
common object file function. 

common object file 

common object file, ldfhread: 
common object file, /number 
common object file, /seek to 

common object file 

common object file 

common object file, /seek to 
common object file, /the index 
common object file, /indexed 
common object file, ldtbseek: 
common object file, linenum: 
common object file, reloc: . 

common object file 

common object file symbol/ 
common object file symbol . 
common object files. . . . 
communication package, 
comparison intrinsic/ . . . 
compile and execute regular 
compile and match routines. 

compiled term file 

complementary error function, 
complex argument, /dimag: 
complex conjugate intrinsic/ 
compute the index of a symbol 
configuration database. . . 
configuration information 
conjg, dconjg: Fortran complex 
conjugate intrinsic function, 
connection, dial: establish . 

constants 

control device 

control 

control operations 

control operations 

control operations 

control options 

control 

conventional names for . . 
conversion, /dcmplx, ichar, 
convert between 3-byte . . 
convert between long integer 
convert date and time to/ 
convert floating-point number 
convert formatted input. . . 

convert string to/ 

convert string to integer, 
core: format of core image . 

core image file 

cos, dcos, ccos: Fortran . . 
cos, tan, asin, acos, atan, 
cosh, dcosh: Fortran . . . 
cosh, tanh: hyperbolic . . . 
cosine intrinsic function. . . 


system (3 F) 
iargc(3F) 
system (3S) 
getarg(3F) 
ar(4) 
a.out (4) 
log 10 (3 F) 
ldfcn (4) 
ldopen (3X) 
ldlread(3X) 
ldclose (3X) 
ldfhread (3X) 
ldlseek(3X) 
ldohseek(3X) 
ldrseek(3X) 
ldshread(3X) 
ldsseek(3X) 
ldtbindex (3X) 
ldtbread(3X) 
ldtbseek (3X) 
linenum (4) 
reloc (4) 
scnhdr (4) 
ldgetname(3X) 
syms (4) 
filehdr(4) 
stdipc(3C) 
strcmp(3F) 
regcmp(3X) 
regexp(5) 
term (4) 
erf(3M) 
aimag(3F) 
conjg (3 F) 
ldtbindex(3X) 
master (4) 
system (4) 
conjg (3 F) 
conjg (3 F) 
dial (3C) 
math (5) 
ioctl (2) 
fcntl (2) 
msgctl (2) 
semctl (2) 
shmctl (2) 
fcntl(5) 
uadmin (2) 
term (5) 
ftype(3F) 
13tol(3C) 
a641(3C) 
ctime(3C) 
ecvt(3C) 
scanf(3S) 
strtod (3C) 
strtol (3C) 
core (4) 
core (4) 
cos(3F) 
trig(3M) 
cosh (3 F) 
sinh(3M) 
cos(3F) 
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/dcosh: Fortran hyperbolic cosine intrinsic function cosh (3 F) 

cpio: format of cpio archive cpio(4) 

cpio: format of cpio archive cpio (4) 

clock: report CPU time used clock(3C) 

rewrite an existing one. creat: create a new file or creat(2) 

file, tmpnam, tempnam: create a name for a temporary tmpnam(3S) 

an existing one. creat: create a new file or rewrite creat (2) 

fork: create a new process fork (2) 

tmpfile: create a temporary file tmpfile(3S) 

channel, pipe: create an interprocess pipe (2) 

umask: set and get file creation mask umask(2) 

optimization package, curses: CRT screen handlin' 1 : and curses(3X) 

generate hashing encryption, crypt, setkey, encrypt: crypt (3C) 

function, sin, dsin, csin: Fortran sine intrinsic sin(3F) 

intrinsic/ sqrt, dsqrt, csqrt: Fortran square root sqrt(3F) 

for terminal, ctermid: generate file name ctermid(3S) 

asctime, tzset: convert date/ ctime, localtime, gmtime, ctime(3C) 

uname: get name of current UNIX system uname(2) 

slot in the utmp file of the current user, /find the ttyslot(3C) 

getcwd: get path-name of current working directory getcwd(3C) 

and optimization package, curses: CRT screen handling curses(3X) 

name of the user, cuserid: get character login cuserid(3S) 

absolute value, abs, iabs, dabs, cabs, zabs: Fortran abs(3F) 

intrinsic function, acos, dacos: Fortran arccosine acos(3F) 

intrinsic function, asin, dasin: Fortran arcsine asin(3F) 

terminfo: terminal capability data base terminfo(4) 

/sgetl: access long integer data in a machine-independent/ sputl(3X) 

plock: lock process, text, or data in memory plock(2) 

call, stat: data returned by stat system stat(5) 

brk, sbrk: change data segment space allocation brk(2) 

types: primitive system data types types (5) 

master: master configuration database master (4) 

intrinsic function, atan, datan: Fortran arctangent atan(3F) 

intrinsic function. atan2, datan2: Fortran arctangent atan2(3F) 

/asctime, tzset: convert date and time to string ctime(3C) 

/idint, real, float, sngl, dble, cmplx, dcmplx, ichar,/ ftype(3F) 

/float, sngl, dble, cmplx, dcmplx, ichar, char: explicit/ ftype(3F) 

conjugate intrinsic/ conjg, dconjg: Fortran complex conjg(3F) 

intrinsic function, cos, dcos, ccos: Fortran cosine cos(3F) 

cosine intrinsic/ cosh, dcosh: Fortran hyperbolic cosh (3 F) 

difference intrinsic/ dim, ddim, idim: positive dim(3F) 

timezone: set default system time zone timezone(4) 

close: close a file descriptor close (2) 

dup: duplicate an open file descriptor dup(2) 

file, access: determine accessibility of a access (2) 

ioctl: control device ioctl(2) 

exponential intrinsic/ exp, dexp, cexp: Fortran exp(3F) 

terminal line connection, dial: establish an out-going dial (3C) 

dim, ddim, idim: positive difference intrinsic/ dim(3F) 

difference intrinsic/ dim, ddim, idim: positive dim(3F) 

of complex argument, aimag, dimag: Fortran imaginary part aimag(3F) 

intrinsic function, aint, dint: Fortran integer part aint(3F) 

dir: format of directories dir(4) 

dir: format of directories dir(4) 

chdir: change working directory chdir(2) 

chroot: change root directory chroot(2) 

unlink: remove directory entry unlink (2) 

path-name of current working directory, getcwd: get getcwd (3C) 

ordinary file, mknod: make a directory, or a special or mknod(2) 

acct: enable or disable process accounting acct(2) 

hypot: Euclidean distance function hypot(3M) 

/lcong48: generate uniformly distributed pseudo-random/ drand48(3C) 

logarithm/ log, alog, dlog, clog: Fortran natural log(3F) 

logarithm/ log 10, alog 10, dlog 10: Fortran common log 10 (3 F) 
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max, maxO, amaxO, maxi, amaxl, 
min, minO, aminO, mini, aminl, 
intrinsic/ mod, amod, 
nearest integer/ anint, 
intrinsic function, dprod: 

/atof: convert string to 
product intrinsic function. 
nrand48, mrand48, jrand48,/ 
transfer-of-sign/ sign, isign, 
intrinsic function, sin, 
intrinsic function, sinh, 
root intrinsic/ sqrt, 
intrinsic function, tan, 
tangent intrinsic/ tanh, 
descriptor, 
descriptor, dup: 
floating-point number to/ 
program, end, etext, 
common assembler and link 
/user, real group, and 
and/ /getegid: get real user, 
accounting, acct: 
encryption, crypt, setkey, 
encrypt: generate hashing 
locations in program, 
/getgrgid, getgmam, setgrent, 
/getpwuid, getpwnam, setpwent, 
utmp/ /pututline, setutent, 
nlist: get 

file, linenum: line number 
file/ /manipulate line number 
/ldnlseek: seek to line number 
/Idnrseek: seek to relocation 
utmp, wtmp: utmp and wtmp 
fgetgrent: get group file 
fgetpwent: get password file 
utmpname: access utmp file 
object file symbol table 
/the index of a symbol table 
/read an indexed symbol table 
putpwent: write password file 
unlink: remove directory 

environ: user 
getenv: return value for 
putenv: change or add value to 
getenv: return Fortran 
mrand48, jrand48,/ drand48, 
complementary error function, 
complementary error/ erf, 
system error/ perror, 
complementary/ erf, erfc: 
function and complementary 
sys errlist, sysnerr: system 
to system calls and 
matherr: 
terminal line/ dial: 
in program, end, 
hypot: 

execlp, execvp: execute a/ 
execvp: execute/ execl, execv, 
execl, execv, execle, execve, 
execve, execlp, execvp: 
regcmp, regex: compile and 


dmaxl: Fortran maximum-value/ max(3F) 

dminl: Fortran minimum-value/ min(3F) 

dmod: Fortran remaindering mod(3F) 

dnint, nint, idnint: Fortran round (3 F) 

double precision product dprod (3 F) 

double-precision number strtod(3C) 

dprod: double precision dprod (3 F) 

drand48, erand48, lrand48, drand48(3C) 

dsign: Fortran sign(3F) 

dsin, csin: Fortran sine sin(3F) 

dsinh: Fortran hyperbolic sine sinh(3F) 

dsqrt, csqrt: Fortran square sqrt (3 F) 

dtan: Fortran tangent tan(3F) 

dtanh: Fortran hyperbolic tanh (3 F) 

dup: duplicate an open file dup(2) 

duplicate an open file dup (2) 

ecvt, fcvt, gcvt: convert ecvt(3C) 

edata: last locations in end(3C) 

editor output, a.out: a.out(4) 

effective group IDs getuid(2) 

effective user, real group, getuid(2) 

enable or disable process acct (2) 

encrypt: generate hashing crypt (3C) 

encryption, crypt, setkey, crypt (3C) 

end, etext, edata: last end(3C) 

endgrent, fgetgrent: get group/ getgrent(3C) 

endpwent, fgetpwent: get/ getpwent(3C) 

endutent, utmpname: access getut(3C) 

entries from name list nlist(3C) 

entries in a common object linenum (4) 

entries of a common object ldlread(3X) 

entries of a section of a/ ldlseek(3X) 

entries of a section of a/ ldrseek(3X) 

entry formats utmp(4) 

entry, /setgrent, endgrent getgrent(3C) 

entry, /setpwent, endpwent, getpwent(3C) 

entry, /setutent, endutent, getut(3C) 

entry, /symbol name for common ldgetname(3X) 

entry of a common object file ldtbindex(3X) 

entry of a common object file ldtbread(3X) 

entry putpwent(3C) 

entry unlink(2) 

environ: user environment environ (5) 

environment environ (5) 

environment name getenv (3C) 

environment . putenv(3C) 

environment variable getenv (3 F) 

erand48, lrand48, nrand48, drand48(3C) 

erf, erfc: error function and erf(3M) 

erfc: error function and erf(3M) 

errno, sys errlist, sys nerr: perror (3C) 

error function and erf(3M) 

error function, /erfc: error erf(3M) 

error messages, /errno, perror (3C) 

error numbers, /introduction intro (2) 

error-handling function matherr (3 M) 

establish an out-going dial(3C) 

etext, edata: last locations end(3C) 

Euclidean distance function hypot (3M) 

execl, execv, execle, execve exec (2) 

execle, execve, execlp, exec (2) 

execlp, execvp: execute a/ exec (2) 

execute a file, /execle, exec (2) 

execute regular expression regcmp(3X) 
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sleep: suspend execution for interval sleep(3C) 

monitor: prepare execution profile monitor (3C) 

profil: execution time profile profil(2) 

execvp: execute a/ execl, execv, execle, execve, execlp, exec (2) 

execute/ execl, execv, execle, execve, execlp, execvp: exec (2) 

/execv, execle, execve, execlp, execvp: execute a file exec (2) 

a new file or rewrite an existing one. creat: create creat(2) 

process, exit, exit: terminate exit (2) 

exit, _exit: terminate process exit (2) 

exponential intrinsic/ exp, dexp, cexp: Fortran exp(3F) 

exponential, logarithm,/ exp, log, log 10, pow, sqrt: exp(3M) 

cmplx, dcmplx, ichar, char: explicit Fortran type/ /dble, ftype(3F) 

exp, dexp, cexp: Fortran exponential intrinsic/ exp(3F) 

exp, log, log 10, pow, sqrt: exponential, logarithm, power,/ exp(3M) 

routines, regexp: regular expression compile and match regexp (5) 

compile and execute regular expression, regcmp, regex: regcmp(3X) 

remainder,/ floor, ceil, fmod, fabs: floor, ceiling, floor (3 M) 

data in a machine-independent fashion., /access long integer sputl(3X) 

/calloc, mallopt, mallinfo: fast main memory allocator malloc(3X) 

abort: generate an IOT fault abort (3C) 

a stream, fclose, fflush: close or flush fclose(3S) 

fcntl: file control fcntl(2) 

fcntl: file control options fcntl (5) 

floating-point number/ ecvt, fcvt, gcvt: convert ecvt(3C) 

fopen, freopen, fdopen: open a stream fopen(3S) 

status inquiries, ferror, feof, clearerr, fileno: stream ferror(3S) 

fileno: stream status/ ferror, feof, clearerr, ferror (3S) 

stream, fclose, fflush: close or flush a fclose (3S) 

word from a/ getc, getchar, fgetc, getw: get character or getc(3S) 

/getgrnam, setgrent, endgrent, fgetgrent: get group file/ getgrent(3C) 

/getpwnam, setpwent, endpwent, fgetpwent: get password file/ getpwent(3C) 

stream, gets, fgets: get a string from a gets(3S) 

times, utime: set file access and modification utime(2) 

ldfcn: common object file access routines ldfcn(4) 

determine accessibility of a file, access: access (2) 

chmod: change mode of file chmod(2) 

change owner and group of a file, chown: chown(2) 

fcntl: file control fcntl (2) 

fcntl: file control options fcntl (5) 

core: format of core image file core (4) 

umask: set and get file creation mask umask(2) 

close: close a file descriptor close (2) 

dup: duplicate an open file descriptor dup(2) 

endgrent, fgetgrent: get group file entry, /setgrent, getgrent(3C) 

fgetpwent: get password file entry, /endpwent, getpwent(3C) 

utmpname: access utmp file entry, /endutent, getut(3C) 

putpwent: write password file entry putpwent(3C) 

execlp, execvp: execute a file, /execv, execle, execve, exec (2) 

Idaopen: open a common object file for reading, ldopen, ldopen(3X) 

ar: common archive file format ar(4) 

pnch: file format for card images pnch(4) 

intro: introduction to file formats intro (4) 

entries of a common object file function, /line number ldlread(3X) 

group: group file group(4) 

files, filehdr: file header for common object filehdr(4) 

file. Idfhread: read the file header of a common object ldfhread(3X) 

ldohseek: seek to the optional file header of a common object/ ldohseek(3X) 

issue: issue identification file issue(4) 

of a member of an archive file, /read the archive header ldahread(3X) 

close a common object file. Idclose, Idaclose: ldclose(3X) 

file header of a common object file. Idfhread: read the Idfhread (3X) 

a section of a common object file, /line number entries of ldlseek(3X) 

file header of a common object file, /seek to the optional ldohseek (3X) 

a section of a common object file, /relocation entries of ldrseek(3X) 
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header of a common object 
section of a common object 
table entry of a common object 
table entry of a common object 
table of a common object 
entries in a common object 
link: link to a 
or a special or ordinary 
ctermid: generate 
mktemp: make a unique 
/find the slot in the utmp 
one. creat: create a new 
passwd: password 
/rewind, ftell: reposition a 
lseek: move read/write 
read: read from 
for a common object 
sccsfile: format of SCCS 
header for a common object 
stat, fstat: get 
/symbol name for common object 
syms: common object 
volume, 
mount: mount a 
ustat: get 
mnttab: mounted 
umount: unmount a 
fsck. checklist: list of 
term: format of compiled term 
tmpfile: create a temporary 
create a name for a temporary 
ftw: walk a 
write: write on a 
common object files, 
ferror, feof, clearerr, 
file header for common object 
format specification in text 
string, format of graphical 
lockf: record locking on 
ttyname, isatty: 
of the current user, ttyslot: 
int, ifix, idint, real, 
ecvt, fcvt, gcvt: convert 
/modf: manipulate parts of 
floor, ceiling, remainder,/ 
floor, ceil, fmod, fabs: 
fclose, fflush: close or 
remainder,/ floor, ceil, 
stream. 

ar: common archive file 
pnch: file 
inode: 
term: 
core: 
cpio: 
dir: 

/graphical primitive string, 
sccsfile: 
file system: 
files, fspec: 
object file symbol table 
intro: introduction to file 
wtmp: utmp and wtmp entry 


file, /indexed/named section 
file, /to an indexed/named 
file, /the index of a symbol 
file, /read an indexed symbol 
file, /seek to the symbol . . 
file, linenum: line number . 

file 

file, /make a directory, . . 
file name for terminal. . . 

file name 

file of the current user. . . 
file or rewrite an existing 

file 

file pointer in a stream. . . 

file pointer 

file 

file, /relocation information 

file 

file, scnhdr: section .... 

file status. . 

file symbol table entry. . . 
file symbol table format, 
file system: format of system 

file system 

file system statistics. . . . 

file system table 

file system 

file systems processed by 

file 

file 

file, tmpnam, tempnam: . . 

file tree 

file 

filehdr: file header for . . . 
fileno: stream status/ . . . 

files, filehdr: 

files, fspec: 

files, /graphical primitive 

files 

find name of a terminal. . . 
find the slot in the utmp file 
float, sngl, dble, cmplx,/ . . 
floating-point number to/ 
floating-point numbers. . . 
floor, ceil, fmod, fabs: . . . 
floor, ceiling, remainder,/ 

flush a stream 

fmod, fabs: floor, ceiling, 
fopen, freopen, fdopen: open a 
fork: create a new process. . 

format 

format for card images. . . 
format of an i-node. . . . 
format of compiled term file., 
format of core image file, 
format of cpio archive. . . 
format of directories. . . . 
format of graphical files, 
format of SCCS file. . . . 
format of system volume, 
format specification in text 
format, syms: common . . 

formats 

formats, utmp, 


ldshread(3X) 
ldsseek(3X) 
ldtbindex(3X) 
ldtbread(3X) 
ldtbseek(3X) 
linenum (4) 
link (2) 
mknod(2) 
ctermid (3S) 
mktemp(3C) 
ttyslot (3C) 
creat(2) 
passwd (4) 
fseek(3S) 
lseek (2) 
read (2) 
reloc(4) 
sccsfile (4) 
scnhdr (4) 
stat (2) 

ldgetname(3X) 
syms (4) 
fs(4) 

mount(2) 

ustat (2) 

mnttab(4) 

umount(2) 

checklist(4) 

term (4) 

tmpfile(3S) 

tmpnam (3S) 

ftw(3C) 

write(2) 

filehdr (4) 

ferror (3S) 

filehdr(4) 

fspec (4) 

gps(4) 

lockf(3C) 

ttyname(3C) 

ttyslot (3C) 

ftype(3F) 

ecvt(3C) 

frexp(3C) 

floor(3M) 

floor(3M) 

fclose (3S) 

floor(3M) 

fopen (3S) 

fork (2) 

ar(4) 

pnch (4) 

inode (4) 

term (4) 

core (4) 

cpio (4) 

dir (4) 

gps(4) 

sccsfile(4) 

fs(4) 

fspec (4) 

syms (4) 

intro(4) 

utmp(4) 
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scanf, fscanf, sscanf: convert 
/vfprintf, vsprintf: print 
/vfprintf, vsprintf: print 
fprintf, sprintf: print 
abs, iabs, dabs, cabs, zabs: 
system/ signal: specify 
function, acos, dacos: 
function, asin, dasin: 
function. atan2, datan2: 

function, atan, datan: 
or, xor, not, lshift, rshift: 

getarg: return 
log 10, aloglO, dloglO: 
intrinsic/ conjg, dconjg: 
function, cos, dcos, ccos: 

getenv: return 
function, exp, dexp, cexp: 
intrinsic/ cosh, dcosh: 
intrinsic/ sinh, dsinh: 
intrinsic/ tanh, dtanh: 
complex/ aimag, dimag: 
function, aint, dint: 
amaxO, maxi, amaxl, dmaxl: 
aminO, mini, aminl, dminl: 
log, alog, dlog, clog: 
anint, dnint, nint, idnint: 
abort: terminate 
functions, mod, amod, dmod: 
function, sin, dsin, csin: 
function, sqrt, dsqrt, csqrt: 
len: return length of 
index: return location of 
issue a shell command from 
function, tan, dtan: 
mclock: return 
intrinsic/ sign, isign, dsign: 
/dcmplx, ichar, char: explicit 
formatted output, printf, 
word on a/ putc, putchar, 
stream, puts, 
input/output, 
memory allocator, malloc, 
mallopt, mallinfo:/ malloc, 
stream, fopen, 
parts of floating-point/ 
getw: get character or word 
gets, fgets: get a string 
getopt: get option letter 
read: read 

system: issue a shell command 
nlist: get entries 
getpw: get name 
formatted input, scanf, 
of file systems processed by 
reposition a file pointer in/ 
text files, 
stat, 

pointer in a/ fseek, rewind, 
communication package. 

Fortran arccosine intrinsic 
Fortran integer part intrinsic 
error/ erf, erfc: error 
Fortran arcsine intrinsic 


formatted input scanf(3S) 

formatted output of a varargs/ vprintf(3S) 

formatted output of a varargs/ vprintf(3X) 

formatted output, printf, printf(3S) 

Fortran absolute value abs(3F) 

Fortran action on receipt of a signal (3 F) 

Fortran arccosine intrinsic acos (3 F) 

Fortran arcsine intrinsic asin (3 F) 

Fortran arctangent intrinsic atan2(3F) 

Fortran arctangent intrinsic atan (3 F) 

Fortran bitwise Boolean/ and bool(3F) 

Fortran command-line argument getarg(3F) 

Fortran common logarithm/ log 10 (3 F) 

Fortran complex conjugate conjg (3 F) 

Fortran cosine intrinsic cos(3F) 

Fortran environment variable getenv (3 F) 

Fortran exponential intrinsic exp(3F) 

Fortran hyperbolic cosine cosh (3 F) 

Fortran hyperbolic sine sinh (3 F) 

Fortran hyperbolic tangent tanh (3 F) 

Fortran imaginary part of aimag (3 F) 

Fortran integer part intrinsic aint (3 F) 

Fortran maximum-value/ /maxO, max(3F) 

Fortran minimum-value/ /minO, min(3F) 

Fortran natural logarithm/ log(3F) 

Fortran nearest integer/ round (3 F) 

Fortran program abort (3F) 

Fortran remaindering intrinsic mod(3F) 

Fortran sine intrinsic sin(3F) 

Fortran square root intrinsic sqrt(3F) 

Fortran string len(3F) 

Fortran substring index (3 F) 

Fortran, system: system (3 F) 

Fortran tangent intrinsic tan(3F) 

Fortran time accounting mclock(3F) 

Fortran transfer-of-sign sign (3 F) 

Fortran type conversion ftype(3F) 

fprintf, sprintf: print printf(3S) 

fputc, putw: put character or putc(3S) 

fputs: put a string on a puts(3S) 

fread, fwrite: binary fread(3S) 

free, realloc, calloc: main malloc (3C) 

free, realloc, calloc, malloc (3X) 

freopen, fdopen: open a fopen (3S) 

frexp, ldexp, modf: manipulate frexp(3C) 

from a stream, /fgetc, getc(3S) 

from a stream gets(3S) 

from argument vector getopt (3C) 

from file read (2) 

from Fortran system (3 F) 

from name list nlist (3C) 

from UID getpw(3C) 

fscanf, sscanf: convert scanf(3S) 

fsck. checklist: list checklist (4) 

fseek, rewind, ftell: fseek (3S) 

fspec: format specification in fspec(4) 

fstat: get file status stat (2) 

ftell: reposition a file fseek(3S) 

ftok: standard interprocess stdipc(3C) 

ftw: walk a file tree ftw(3C) 

function, acos, dacos: acos (3 F) 

function, aint, dint: aint(3F) 

function and complementary erf(3M) 

function, asin, dasin: asin (3 F) 
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Fortran arctangent intrinsic 
Fortran arctangent intrinsic 
complex conjugate intrinsic 

ccos: Fortran cosine intrinsic 
hyperbolic cosine intrinsic 
precision product intrinsic 
and complementary error 
Fortran exponential intrinsic 
gamma: log gamma 
hypot: Euclidean distance 
of a common object file 
common logarithm intrinsic 
natural logarithm intrinsic 
matherr: error-handling 
prof: profile within a 
transfer-of-sign intrinsic 
csin: Fortran sine intrinsic 
hyperbolic sine intrinsic 
Fortran square root intrinsic 
sys3b: machine specific 
Fortran tangent intrinsic 
hyperbolic tangent intrinsic 
math: math 
/field manipulation intrinsic 
jO, jl, jn, yO, yl, yn: Bessel 
Fortran bitwise Boolean 
positive difference intrinsic 
logarithm, power, square root 
remainder, absolute value 
dmaxl: Fortran maximum-value 
dminl: Fortran minimum-value 
Fortran remaindering intrinsic 
Fortran nearest integer 
sinh, cosh, tanh: hyperbolic 
string comparison intrinsic 
atan, atan2: trigonometric 
fread, 
gamma: log 

number to string, ecvt, fcvt, 
abort: 

terminal, ctermid: 
crypt, setkey, encrypt: 
/srand48, seed48, lcong48: 
srand: simple random-number 
rand, srand: random-number 
gets, fgets: 
ulimit: 
the user, cuserid: 
getc, getchar, fgetc, getw: 

nlist: 

umask: set and 
stat, fstat: 
ustat: 

/setgrent, endgrent, fgetgrent: 

getlogin: 
msgget: 
getpw: 
system, uname: 
argument vector, getopt: 
/setpwent, endpwent, fgetpwent: 
working directory, getcwd: 

times, times: 
and/ getpid, getpgrp, getppid: 


function. atan2, datan2: . . . 
function, atan, datan: . . . . 
function, /dconjg: Fortran . . 

function, cos, dcos, 

function, /dcosh: Fortran . . 
function, dprod: double . . . 
function, /error function . . 
function, exp, dexp, cexp: . . 

function 

function 

function, /line number entries 
function. /dloglO: Fortran . . 
function, /dlog, clog: Fortran 

function 

function 

function, /dsign: Fortran . . 

function, sin, dsin, 

function, /dsinh: Fortran . . 
function, sqrt, dsqrt, csqrt: . . 

function 

function, tan, dtan: 

function, /dtanh: Fortran . . 
functions and constants. . . . 
functions and subroutines.,/ 

functions 

functions, /lshift, rshift: . . . 
functions, dim, ddim, idim: 
functions, /sqrt: exponential, . 
functions, /floor, ceiling, . . 
functions, /maxi, amaxl, . . 
functions, /mini, aminl, . . 
functions, mod, amod, dmod: 
functions, /nint, idnint: . . . 

functions 

functions. /Igt, lie, lit: . . . 
functions, /tan, asin, acos, . . 
fwrite: binary input/output. 

gamma function 

gamma: log gamma function, 
gcvt: convert floating-point . . 
generate an IOT fault. . . . 
generate file name for ... . 
generate hashing encryption. . 
generate uniformly distributed/ 

generator, rand, 

generator, irand, 

get a string from a stream, 
get and set user limits. . . . 
get character login name of 
get character or word from a/ 
get entries from name list. . . 

get file creation mask 

get file status 

get file system statistics. . . . 

get group file entry 

get login name 

get message queue 

get name from UID 

get name of current UNIX 
get option letter from .... 
get password file entry. . . . 
get path-name of current . . 
get process and child process . 
get process, process group, . . 


atan2(3F) 

atan(3F) 

conjg(3F) 

cos(3F) 

cosh (3 F) 

dprod (3 F) 

erf(3M) 

exp(3F) 

gamma (3M) 

hypot(3M) 

ldlread(3X) 

loglO(3F) 

log(3F) 

matherr(3M) 

prof(5) 

sign(3F) 

sin(3F) 

sinh(3F) 

sqrt (3 F) 

sys3b(2) 

tan(3F) 

tanh (3 F) 

math (5) 

mil(3F) 

bessel(3M) 

bool (3 F) 

dim(3F) 

exp(3M) 

floor(3M) 

max(3F) 

min(3F) 

mod(3F) 

round (3F) 

sinh(3M) 

strcmp(3F) 

trig(3M) 

fread (3S) 

gamma (3M) 

gamma (3M) 

ecvt(3C) 

abort (3C) 

ctermid (3S) 

crypt(3C) 

drand48(3C) 

rand(3C) 

rand(3F) 

gets(3S) 

ulimit(2) 

cuserid (3S) 

getc(3S) 

nlist (3C) 

umask(2) 

stat (2) 

ustat (2) 

getgrent(3C) 

getlogin (3C) 

msgget (2) 

getpw (3C) 

uname (2) 

getopt (3C) 

getpwent(3C) 

getcwd (3 C) 

times (2) 

getpid (2) 
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/geteuid, getgid, getegid: get real user, effective user,/ getuid(2) 

semget: get set of semaphores semget(2) 

shmget: get shared memory segment shmget(2) 

time: get time time(2) 

command-line argument, getarg: return Fortran getarg(3F) 

get character or word from a/ getc, getchar, fgetc, getw: getc(3S) 

character or word from/ getc, getchar, fgetc, getw: get getc(3S) 

current working directory, getcwd: get path-name of . getcwd(3C) 

getuid, geteuid, getgid, getegid: get real user,/ getuid(2) 

environment variable, getenv: return Fortran getenv(3F) 

environment name, getenv: return value for getenv (3C) 

real user, effective/ getuid, geteuid, getgid, getegid: get getuid (2) 

user,/ getuid, geteuid, getgid, getegid: get real getuid (2) 

setgrent, endgrent,/ getgrent, getgrgid, getgrnam, getgrent(3C) 

endgrent,/ getgrent, getgrgid, getgrnam, setgrent, getgrent (3C) 

getgrent, getgrgid, getgrnam, setgrent, endgrent,/ getgrent (3C) 

getlogin: get login name getlogin(3C) 

argument vector, getopt: get option letter from getopt(3C) 

getpass: read a password getpass(3C) 

process group, and/ getpid, getpgrp, getppid: get process, getpid(2) 

process, process group, and/ getpid, getpgrp, getppid: get getpid (2) 

group, and/ getpid, getpgrp, getppid: get process, process getpid (2) 

getpw: get name from UID getpw(3C) 

setpwent, endpwent,/ getpwent, getpwuid, getpwnam, getpwent(3C) 

getpwent, getpwuid, getpwnam, setpwent, endpwent,/ getpwent (3C) 

endpwent,/ getpwent, getpwuid, getpwnam, setpwent, getpwent (3C) 

a stream, gets, fgets: get a string from gets(3S) 

and terminal settings used by getty. gettydefs: speed gettydefs(4) 

settings used by getty. gettydefs: speed and terminal gettydefs (4) 

getegid: get real user,/ getuid, geteuid, getgid, getuid (2) 

pututline, setutent,/ getutent, getutid, getutline, getut(3C) 

setutent, endutent,/ getutent, getutid, getutline, pututline, getut(3C) 

setutent,/ getutent, getutid, getutline, pututline, getut(3C) 

from a/ getc, getchar, fgetc, getw: get character or word getc(3S) 

convert/ ctime, localtime, gmtime, asctime, tzset: ctime(3C) 

setjmp, longjmp: non-local goto setjmp(3C) 

string, format of graphical/ gps: graphical primitive gps(4) 

primitive string, format of graphical files, /graphical gps (4) 

format of graphical/ gps: graphical primitive string, gps (4) 

plot: graphics interface plot (4) 

subroutines, plot: graphics interface plot(3X) 

/user, effective user, real group, and effective group/ getuid (2) 

/getppid: get process, process group, and parent process IDs getpid (2) 

endgrent, fgetgrent: get group file entry, /setgrent, getgrent (3C) 

group: group file group (4) 

group: group file group (4) 

setpgrp: set process group ID setpgrp(2) 

real group, and effective group IDs. /effective user, getuid (2) 

setuid, setgid: set user and group IDs setuid(2) 

chown: change owner and group of a file chown(2) 

a signal to a process or a group of processes, /send kill (2) 

ssignal, gsignal: software signals ssignal(3C) 

varargs: handle variable argument list varargs(5) 

package, curses: CRT screen handling and optimization curses (3X) 

hcreate, hdestroy: manage hash search tables, hsearch, hsearch(3C) 

setkey, encrypt: generate hashing encryption, crypt, crypt (3C) 

search tables, hsearch, hcreate, hdestroy: manage hash hsearch (3C) 

tables, hsearch, hcreate, hdestroy: manage hash search hsearch (3C) 

file, scnhdr: section header for a common object scnhdr(4) 

files, filehdr: file header for common object filehdr(4) 

file, ldfhread: read the file header of a common object ldfhread(3X) 

/seek to the optional file header of a common object/ ldohseek(3X) 

/read an indexed/named section header of a common object/ ldshread(3X) 

ldahread: read the archive header of a member of an/ ldahread(3X) 
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manage hash search tables, 
cosh, dcosh: Fortran 
sinh, cosh, tanh: 

sinh, dsinh: Fortran 
tanh, dtanh: Fortran 
function. 

Fortran absolute value, abs, 
ishftc, ibit field/ ior, 
command line arguments, 
subroutines., btest, ibset, 
not, ieor, ishft, ishftc, 
/and subroutines., btest, 
/sngl, dble, cmplx, dcmplx, 
setpgrp: set process group 
issue: issue 
intrinsic/ dim, ddim, 
dble, cmplx,/ int, ifix, 
integer/ anint, dnint, nint, 
group, and parent process 
group, and effective group 
setgid: set user and group 
field/ ior, iand, not, 
sngl, dble, cmplx,/ int, 
core: format of core 
pnch: file format for card 
aimag, dimag: Fortran 
of a / Idtbindex: compute the 
Fortran substring, 
a common/ ldtbread: read an 
ldshread, ldnshread: read an 
ldsseek, ldnsseek: seek to an 
inittab: script for the 
process, popen, pclose: 

process. 

inode: format of an 
sscanf: convert formatted 
push character back into 
fread, fwrite: binary 
stdio: standard buffered 
fileno: stream status 
sngl, dble, cmplx, dcmplx,/ 
abs: return 
/164a: convert between long 
sputl, sgetl: access long 
nint, idnint: Fortran nearest 
function, aint, dint: Fortran 
atol, atoi: convert string to 
/ltol3: convert between 3-byte 
3-byte integers and long 
plot: graphics 
plot: graphics 
pipe: create an 
package, ftok: standard 
sleep: suspend execution for 
acos, dacos: Fortran arccosine 
dint: Fortran integer part 
asin, dasin: Fortran arcsine 
datan2: Fortran arctangent 
datan: Fortran arctangent 
Fortran complex conjugate 
dcos, ccos: Fortran cosine 
Fortran hyperbolic cosine 
double precision product 


hsearch, hcreate, hdestroy: . . 
hyperbolic cosine intrinsic/ 
hyperbolic functions 

hyperbolic sine intrinsic/ . . 
hyperbolic tangent intrinsic/ . 
hypot: Euclidean distance . . 
iabs, dabs, cabs, zabs: .... 
iand, not, ieor, ishft, .... 
iargc: return the number of 
ibclr, mvbits: bit. /and . . . 
ibit field manipulation/ /iand, 
ibset, ibclr, mvbits: bit. . . . 
ichar, char: explicit Fortran/ . 

ID 

identification file 

idim: positive difference . . . 
idint, real, float, sngl, .... 
idnint: Fortran nearest . . . 
IDs. /get process, process . . 
IDs. /effective user, real . . 

IDs. setuid, 

ieor, ishft, ishftc, ibit . . . . 
ifix, idint, real, float, .... 

image file 

images 

imaginary part of complex/ 
index of a symbol table entry 
index: return location of . . . 
indexed symbol table entry of 
indexed/named section header/ 
indexed/named section of a/ . 

init process 

initiate pipe to/from a ... 
inittab: script for the init . . 
inode: format of an i-node. . . 

i-node 

input, scanf, fscanf, . . . . 
input stream, ungetc: . . . . 

input/output 

input/output package 

inquiries, /feof, clearerr, . . 
int, ifix, idint, real, float, . . 
integer absolute value. . . . 
integer and base-64 ASCII/ . 

integer data in a/ 

integer functions, /dnint, . . 
integer part intrinsic . . . . 

integer, strtol, 

integers and long integers. . . 
integers, /convert between . . 

interface 

interface subroutines 

interprocess channel 

interprocess communication 

interval 

intrinsic function 

intrinsic function, aint, . . . 

intrinsic function 

intrinsic function. atan2, . . 
intrinsic function, atan, . . . 
intrinsic function, /dconjg: 
intrinsic function, cos, . . . 
intrinsic function, /dcosh: . . 
intrinsic function, dprod: . . 


. hsearch (3C) 

. cosh (3 F) 

. sinh(3M) 

. sinh(3F) 

. tanh(3F) 

. hypot (3 M) 

. abs(3F) 

. mil(3F) 

. iargc (3 F) 

. mil(3F) 

. mil(3F) 

. mil(3F) 

. ftype(3F) 

. setpgrp (2) 

. issue(4) 

. dim(3F) 

. ftype(3F) 

. round (3F) 

. getpid(2) 

. getuid(2) 

. setuid (2) 

. mil(3F) 

. ftype(3F) 

. core (4) 

. pnch (4) 

. aimag(3F) 

. ldtbindex(3X) 
. index (3 F) 

. ldtbread (3X) 

. ldshread(3X) 

. ldsseek (3X) 

. inittab(4) 

. popen (3S) 

. inittab(4) 

. inode (4) 

. inode (4) 

. scanf(3S) 

. ungetc(3S) 

. fread (3S) 

. stdio(3S) 

. ferror(3S) 

. ftype(3F) 

. abs(3C) 

. a641(3C) 

. sputl (3X) 

. round (3 F) 

. aint(3F) 

. strtol (3C) 

. 13tol(3C) 

. 13tol(3C) 

. plot (4) 

. plot(3X) 

. pipe (2) 

. stdipc(3C) 

. sleep(3C) 

. acos (3 F) 

. aint(3F) 

. asin (3 F) 

. atan2(3F) 

. atan(3F) 

. conjg(3F) 

. cos(3F) 

. cosh (3 F) 

. dprod (3 F) 
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cexp: Fortran exponential 
Fortran common logarithm 
Fortran natural logarithm 
Fortran transfer-of-sign 
sin, dsin, csin: Fortran sine 
dsinh: Fortran hyperbolic sine 
csqrt: Fortran square root 
tan, dtan: Fortran tangent 
Fortran hyperbolic tangent 
/ibit field manipulation 
idim: positive difference 
dmod: Fortran remaindering 
lie, lit: string comparison 
formats, 
miscellany, 
subroutines and libraries, 
calls and error numbers. 

intro: 

intro: 

and libraries, intro: 
and error numbers, intro: 

ishftc, ibit field/ 
abort: generate an 
random-number generator, 
/islower, isdigit, isxdigit, 
isdigit, isxdigit, isalnum,/ 
/isprint, isgraph, iscntrl, 
terminal, ttyname, 
/ispunct, isprint, isgraph, 
isalpha, isupper, islower, 
/isspace, ispunct, isprint, 
ior, iand, not, ieor, 
ior, iand, not, ieor, ishft, 
transfer-of-sign/ sign, 
isalnum,/ isalpha, isupper, 
/isalnum, isspace, ispunct, 
/isxdigit, isalnum, isspace, 
/isdigit, isxdigit, isalnum, 
Fortran, system: 
system: 
issue: 
file. 

isxdigit, isalnum,/ isalpha, 
/isupper, islower, isdigit, 
functions, 
functions. jO, 
functions. jO, jl, 
/lrand48, nrand48, mrand48, 
process or a group of/ 
3 -byte integers and long/ 
integer and base-64/ a641, 
/jrand48, srand48, seed48, 
object file, ldclose, 
header of a member of an/ 
file for reading, ldopen, 
common object file, 
of floating-point/ frexp, 
access routines, 
of a common object file, 
name for common object file/ 
line number entries/ ldlread, 
number/ ldlread, ldlinit, 
manipulate line number/ 


intrinsic function, /dexp, exp(3F) 

intrinsic function. /dloglO: log 10 (3 F) 

intrinsic function, /clog: log(3F) 

intrinsic function, /dsign: sign (3 F) 

intrinsic function sin(3F) 

intrinsic function, sinh, sinh(3F) 

intrinsic function, /dsqrt, sqrt(3F) 

intrinsic function tan(3F) 

intrinsic function, /dtanh: tanh(3F) 

intrinsic functions and/ mil(3F) 

intrinsic functions, /ddim, dim(3F) 

intrinsic functions, /amod, mod(3F) 

intrinsic functions, /lgt, strcmp(3F) 

intro: introduction to file intro (4) 

intro: introduction to intro (5) 

intro: introduction to intro (3) 

intro: introduction to system intro (2) 

introduction to file formats intro (4) 

introduction to miscellany intro (5) 

introduction to subroutines intro (3) 

introduction to system calls intro (2) 

ioctl: control device ioctl(2) 

ior, iand, not, ieor, ishft, mil(3F) 

IOT fault abort (3C) 

irand, rand, srand: rand(3F) 

isalnum, isspace, ispunct,/ ctype(3C) 

isalpha, isupper, islower, ctype(3C) 

isascii: classify characters ctype(3C) 

isatty: find name of a ttyname(3C) 

iscntrl, isascii: classify/ ctype(3C) 

isdigit, isxdigit, isalnum,/ ctype(3C) 

isgraph, iscntrl, isascii:/ ctype(3C) 

ishft, ishftc, ibit field/ mil(3F) 

ishftc, ibit field/ mil(3F) 

isign, dsign: Fortran sign (3 F) 

islower, isdigit, isxdigit, ctype(3C) 

isprint, isgraph, iscntrl,/ ctype(3C) 

ispunct, isprint, isgraph,/ ctype(3C) 

isspace, ispunct, isprint,/ ctype(3C) 

issue a shell command from system (3 F) 

issue a shell command system (3S) 

issue identification file issue (4) 

issue: issue identification issue (4) 

isupper, islower, isdigit, ctype(3C) 

isxdigit, isalnum, isspace,/ ctype(3C) 

jO, jl, jn, yO, yl, yn: Bessel bessel(3M) 

jl, jn, yO, yl, yn: Bessel bessel(3M) 

jn, yO, yl, yn: Bessel bessel(3M) 

jrand48, srand48, seed48,/ drand48(3C) 

kill: send a signal to a kill (2) 

13tol, ltol3: convert between 13tol(3C) 

164a: convert between long a641(3C) 

lcong48: generate uniformly/ drand48(3C) 

ldaclose: close a common ldclose (3X) 

ldahread: read the archive ldahread(3X) 

ldaopen: open a common object ldopen (3X) 

ldclose, ldaclose: close a ldclose (3X) 

ldexp, modf: manipulate parts frexp (3C) 

ldfcn: common object file ldfcn(4) 

ldfhread: read the file header ldfhread(3X) 

Idgetname: retrieve symbol ldgetname(3X) 

ldlinit, ldlitem: manipulate ldlread (3X) 

ldlitem: manipulate line ldlread (3X) 

ldlread, ldlinit, ldlitem: ldlread (3X) 
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line number entries of a/ ldlseek, ldnlseek: seek to ldlseek(3X) 

entries of a section/ ldlseek, ldnlseek: seek to line number ldlseek(3X) 

entries of a section/ ldrseek, ldnrseek: seek to relocation ldrseek(3X) 

indexed/named/ ldshread, ldnshread: read an ldshread(3X) 

indexed/named/ ldsseek, ldnsseek: seek to an ldsseek(3X) 

file header of a common/ Idohseek: seek to the optional ldohseek(3X) 

object file for reading, ldopen, ldaopen: open a common ldopen(3X) 

relocation entries of a/ ldrseek, ldnrseek: seek to ldrseek (3 X) 

indexed/named section header/ ldshread, ldnshread: read an ldshread (3X) 

indexed/named section of a/ ldsseek, ldnsseek: seek to an ldsseek (3X) 

of a symbol table entry of a/ ldtbindex: compute the index ldtbindex(3X) 

symbol table entry of a/ ldtbread: read an indexed ldtbread(3X) 

table of a common object/ ldtbseek: seek to the symbol ldtbseek(3X) 

string, len: return length of Fortran len(3F) 

len: return length of Fortran string len(3F) 

getopt: get option letter from argument vector getopt(3C) 

update, lsearch, lfind: linear search and lsearch(3C) 

comparison intrinsic/ lge, lgt, lie, lit: string strcmp(3F) 

comparison intrinsic/ lge, lgt, lie, lit: string strcmp(3F) 

to subroutines and libraries, /introduction intro (3) 

ulimit: get and set user limits ulimit(2) 

return the number of command line arguments, iargc: iargc(3F) 

an out-going terminal line connection, /establish dial(3C) 

common object file, linenum: line number entries in a linenum(4) 

/ldlinit, ldlitem: manipulate line number entries of a/ ldlread(3X) 

ldlseek, ldnlseek: seek to line number entries of a/ ldlseek(3X) 

lsearch, lfind: linear search and update lsearch (3C) 

in a common object file, linenum: line number entries linenum (4) 

a.out: common assembler and link editor output a.out(4) 

link: link to a file link(2) 

link: link to a file link(2) 

nlist: get entries from name list nlist(3C) 

by fsck. checklist: list of file systems processed checklist (4) 

handle variable argument list, varargs: varargs(5) 

output of a varargs argument list, /print formatted vprintf(3S) 

output of a varargs argument list, /print formatted vprintf(3X) 

intrinsic/ lge, lgt, lie, lit: string comparison strcmp(3F) 

intrinsic/ lge, lgt, lie, lit: string comparison strcmp(3F) 

tzset: convert date/ ctime, localtime, gmtime, asctime, ctime(3C) 

index: return location of Fortran substring index (3 F) 

end, etext, edata: last locations in program end(3C) 

memory, plock: lock process, text, or data in plock(2) 

files, lockf: record locking on lockf(3C) 

lockf: record locking on files. lockf(3C) 

natural logarithm intrinsic/ log, alog, dlog, clog: Fortran log(3F) 

gamma: log gamma function gamma (3M) 

exponential, logarithm,/ exp, log, log 10, pow, sqrt: exp(3M) 

common logarithm intrinsic/ log 10, alog 10, dlog 10: Fortran log 10 (3 F) 

logarithm, power,/ exp, log, log 10, pow, sqrt: exponential, exp(3M) 

/aloglO, dloglO: Fortran common logarithm intrinsic function logl0(3F) 

/dlog, clog: Fortran natural logarithm intrinsic function log(3F) 

/log 10, pow, sqrt: exponential, logarithm, power, square root/ exp(3M) 

getlogin: get login name getlogin(3C) 

cuserid: get character login name of the user cuserid(3S) 

logname: return login name of user logname(3X) 

user, logname: return login name of logname (3X) 

a641, 164a: convert between long integer and base-64 ASCII/ a641(3C) 

sputl, sgetl: access long integer data in a/ sputl(3X) 

between 3-byte integers and long integers. /ltol3: convert 13tol(3C) 

setjmp, longjmp: non-local goto setjmp(3C) 

jrand48,/ drand48, erand48, lrand48, nrand48, mrand48, drand48(3C) 

and update, lsearch, lfind: linear search lsearch (3C) 

pointer, lseek: move read/write file lseek(2) 

bitwise/ and, or, xor, not, lshift, rshift: Fortran bool (3 F) 
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integers and long/ 13tol, ltol3: convert between 3-byte 13tol(3C) 

sys3b: machine specific function sys3b(2) 

values: machine-dependent values values (5) 

/access long integer data in a machine-independent fashion sputl(3X) 

malloc, free, realloc, calloc: main memory allocator malloc(3C) 

/mallopt, mallinfo: fast main memory allocator malloc (3X) 

or ordinary file, mknod: make a directory, or a special mknod(2) 

mktemp: make a unique file name mktemp(3C) 

/realloc, calloc, mallopt, mallinfo: fast main memory/ malloc (3X) 

main memory allocator, malloc, free, realloc, calloc: malloc(3C) 

mallopt, mallinfo: fast main/ malloc, free, realloc, calloc, malloc (3X) 

malloc, free, realloc, calloc, mallopt, mallinfo: fast main/ malloc (3X) 

/tfind, tdelete, twalk: manage binary search trees tsearch(3C) 

hsearch, hcreate, hdestroy: manage hash search tables hsearch(3C) 

of/ ldlread, ldlinit, ldlitem: manipulate line number entries ldlread(3X) 

frexp, ldexp, modf: manipulate parts of/ frexp(3C) 

ishft, ishftc, ibit field manipulation intrinsic/ /ieor, mil(3F) 

ascii: map of ASCII character set ascii (5) 

set and get file creation mask, umask: umask(2) 

master: master configuration database master (4) 

database, master: master configuration master (4) 

regular expression compile and match routines, regexp: regexp (5) 

math: math functions and constants math (5) 

constants, math: math functions and math (5) 

function, matherr: error-handling matherr(3M) 

dmaxl: Fortran maximum-value/ max, maxO, amaxO, maxi, amaxl, max(3F) 

dmaxl: Fortran/ max, maxO, amaxO, maxi, amaxl, max(3F) 

max, maxO, amaxO, maxi, amaxl, dmaxl: Fortran/ max(3F) 

/maxi, amaxl, dmaxl: Fortran maximum-value functions max(3F) 

accounting, mclock: return Fortran time mclock(3F) 

memcpy, memset: memory/ memccpy, memchr, memcmp, memory (3C) 

memset: memory/ memccpy, memchr, memcmp, memcpy, memory (3C) 

operations, memccpy, memchr, memcmp, memcpy, memset: memory .... memory (3C) 

memccpy, memchr, memcmp, memcpy, memset: memory/ memory (3C) 

free, realloc, calloc: main memory allocator, malloc, malloc (3C) 

mallopt, mallinfo: fast main memory allocator, /calloc malloc (3X) 

shmctl: shared memory control operations shmctl(2) 

memcmp, memcpy, memset: memory operations, /memchr, memory (3C) 

shmop: shared memory operations shmop(2) 

lock process, text, or data in memory, plock: plock(2) 

shmget: get shared memory segment shmget(2) 

/memchr, memcmp, memcpy, memset: memory operations memory (3C) 

msgctl: message control operations msgctl(2) 

msgop: message operations msgop(2) 

msgget: get message queue msgget(2) 

sys nerr: system error messages, /errno, sys errlist, perror(3C) 

dminl: Fortran minimum-value/ min, minO, aminO, mini, aminl, min(3F) 

dminl: Fortran/ min, minO, aminO, mini, aminl, min(3F) 

min, minO, aminO, mini, aminl, dminl: Fortran/ min(3F) 

/mini, aminl, dminl: Fortran minimum-value functions min(3F) 

special or ordinary file, mknod: make a directory, or a mknod (2) 

name, mktemp: make a unique file mktemp (3C) 

table, mnttab: mounted file system mnttab(4) 

remaindering intrinsic/ mod, amod, dmod: Fortran mod(3F) 

chmod: change mode of file chmod(2) 

floating-point/ frexp, ldexp, modf: manipulate parts of frexp(3C) 

utime: set file access and modification times utime(2) 

profile, monitor: prepare execution monitor (3C) 

mount: mount a file system mount (2) 

mount: mount a file system mount (2) 

mnttab: mounted file system table mnttab(4) 

lseek: move read/write file pointer lseek(2) 

/erand48, lrand48, nrand48, mrand48, jrand48, srand48,/ drand48(3C) 

operations, msgctl: message control msgctl (2) 
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msgget: get message queue msgget(2) 

msgop: message operations msgop(2) 

btest, ibset, ibclr, mvbits: bit. /subroutines., mil(3F) 

log, alog, dlog, clog: Fortran natural logarithm intrinsic/ log(3F) 

/dnint, nint, idnint: Fortran nearest integer functions round (3 F) 

process, nice: change priority of a nice (2) 

integer/ anint, dnint, nint, idnint: Fortran nearest . round (3 F) 

list, nlist: get entries from name nlist(3C) 

setjmp, longjmp: non-local goto setjmp(3C) 

field manipulation/ ior, iand, not, ieor, ishft, ishftc, ibit mil(3F) 

bitwise Boolean/ and, or, xor, not, lshift, rshift: Fortran bool (3 F) 

drand48, erand48, lrand48, nrand48, mrand48, jrand48,/ drand48(3C) 

ldfcn: common object file access routines ldfcn(4) 

ldopen, ldaopen: open a common object file for reading ldopen(3X) 

number entries of a common object file function, /line ldlread(3X) 

ldaclose: close a common object file, ldclose, ldclose(3X) 

the file header of a common object file, ldfhread: read ldfhread(3X) 

of a section of a common object file, /number entries ldlseek(3X) 

file header of a common object file, /to the optional ldohseek(3X) 

of a section of a common object file, /entries ldrseek(3X) 

section header of a common object file, /indexed/named ldshread(3X) 

section of a common object file, /indexed/named ldsseek(3X) 

symbol table entry of a common object file, /the index of a ldtbindex(3X) 

symbol table entry of a common object file, /read an indexed ldtbread(3X) 

the symbol table of a common object file, /seek to ldtbseek(3X) 

number entries in a common object file, linenum: line linenum(4) 

information for a common object file, /relocation reloc(4) 

section header for a common object file, scnhdr: scnhdr(4) 

entry, /symbol name for common object file symbol table ldgetname(3X) 

format, syms: common object file symbol table syms(4) 

file header for common object files, filehdr: filehdr(4) 

reading, ldopen, ldaopen: open a common object file for ldopen (3X) 

fopen, freopen, fdopen: open a stream . fopen(3S) 

dup: duplicate an open file descriptor dup(2) 

open: open for reading or writing open (2) 

writing, open: open for reading or open (2) 

memcmp, memcpy, memset: memory operations, memccpy, memchr, memory (3C) 

msgctl: message control operations msgctl(2) 

msgop: message operations msgop (2) 

semctl: semaphore control operations semctl(2) 

semop: semaphore operations semop(2) 

shmctl: shared memory control operations shmctl(2) 

shmop: shared memory operations shmop(2) 

strcspn, strtok: string operations, /strpbrk, strspn, string(3C) 

CRT screen handling and optimization package, curses: curses (3X) 

vector, getopt: get option letter from argument getopt(3C) 

common/ ldohseek: seek to the optional file header of a ldohseek(3X) 

fcntl: file control options fcntl (5) 

Fortran bitwise Boolean/ and, or, xor, not, lshift, rshift: bool (3 F) 

a directory, or a special or ordinary file, mknod: make mknod(2) 

dial: establish an out-going terminal line/ dial (3C) 

assembler and link editor output, a.out: common a.out(4) 

/vsprintf: print formatted output of a varargs argument/ vprintf(3S) 

/vsprintf: print formatted output of a varargs argument/ vprintf(3X) 

sprintf: print formatted output, printf, fprintf, printf(3S) 

chown: change owner and group of a file chown(2) 

handling and optimization package, curses: CRT screen curses (3X) 

standard buffered input/output package, stdio: stdio(3S) 

interprocess communication package, ftok: standard stdipc(3C) 

link editor output, a.out: common assembler and a.out (4) 

process, process group, and parent process IDs. /get getpid(2) 

passwd: password file passwd(4) 

/endpwent, fgetpwent: get password file entry getpwent(3C) 

putpwent: write password file entry putpwent(3C) 
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passwd: password file passwd(4) 

getpass: read a password getpass(3C) 

directory, getcwd: get path-name of current working getcwd(3C) 

signal, pause: suspend process until pause (2) 

a process, popen, pclose: initiate pipe to/from popen(3S) 

sys_nerr: system error/ perror, errno, sys errlist, perror(3C) 

channel, pipe: create an interprocess pipe (2) 

popen, pclose: initiate pipe to/from a process popen (3S) 

data in memory, plock: lock process, text, or plock(2) 

plot: graphics interface plot (4) 

subroutines, plot: graphics interface plot (3 X) 

images, pnch: file format for card pnch(4) 

ftell: reposition a file pointer in a stream, /rewind, fseek(3S) 

lseek: move read/ write file pointer lseek(2) 

to/from a process, popen, pclose: initiate pipe popen (3S) 

functions, dim, ddim, idim: positive difference intrinsic dim(3F) 

logarithm,/ exp, log, log 10, pow, sqrt: exponential, exp(3M) 

/sqrt: exponential, logarithm, power, square root functions exp(3M) 

function, dprod: double precision product intrinsic dprod(3F) 

monitor: prepare execution profile monitor (3C) 

graphical/ gps: graphical primitive string, format of gps(4) 

types: primitive system data types types (5) 

vprintf, vfprintf, vsprintf: print formatted output of a/ vprintf(3S) 

vprintf, vfprintf, vsprintf: print formatted output of a/ vprintf(3X) 

printf, fprintf, sprintf: print formatted output printf(3S) 

print formatted output, printf, fprintf, sprintf: printf (3S) 

nice: change priority of a process nice (2) 

acct: enable or disable process accounting acct(2) 

alarm: set a process alarm clock alarm (2) 

times, times: get process and child process times (2) 

exit, exit: terminate process exit (2) 

fork: create a new process fork (2) 

/getpgrp, getppid: get process, process group, and parent/ getpid(2) 

setpgrp: set process group ID setpgrp(2) 

process group, and parent process IDs. /get process, getpid(2) 

inittab: script for the init process inittab(4) 

nice: change priority of a process nice (2) 

kill: send a signal to a process or a group of/ kill (2) 

initiate pipe to/from a process, popen, pclose: popen (3S) 

getpid, getpgrp, getppid: get process, process group, and/ getpid(2) 

memory, plock: lock process, text, or data in plock (2) 

times: get process and child process times times (2) 

wait: wait for child process to stop or terminate wait (2) 

ptrace: process trace ptrace(2) 

pause: suspend process until signal pause (2) 

list of file systems processed by fsck. checklist: checklist (4) 

to a process or a group of processes, /send a signal kill (2) 

dprod: double precision product intrinsic function dprod (3 F) 

function, prof: profile within a prof (5) 

profile, profil: execution time profil(2) 

monitor: prepare execution profile monitor (3C) 

profil: execution time profile profil (2) 

profile: system-wide user profile profile (4) 

profile, profile: system-wide user profile (4) 

prof: profile within a function prof(5) 

/generate uniformly distributed pseudo-random numbers drand48(3C) 

ptrace: process trace ptrace (2) 

stream, ungetc: push character back into input ungetc(3S) 

put character or word on a/ putc, putchar, fputc, putw: putc(3S) 

character or word on a/ putc, putchar, fputc, putw: put putc(3S) 

environment, putenv: change or add value to putenv(3C) 

entry, putpwent: write password file putpwent(3C) 

stream, puts, fputs: put a string on a puts(3S) 

getutent, getutid, getutline, pututline, setutent, endutent,/ getut(3C) 
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a/ putc, putchar, fputc, 

msgget: get message 
qsort: 

generator, irand, 
random-number generator, 
rand, srand: simple 
irand, rand, srand: 

getpass: 

entry of a common/ ldtbread: 
header/ ldshread, ldnshread: 

read: 

member of an/ ldahread: 
common object file, ldfhread: 
open a common object file for 
open: open for 
lseek: move 
cmplx,/ int, ifix, idint, 
allocator, malloc, free, 
mallinfo: fast/ malloc, free, 
specify what to do upon 
/specify Fortran action on 
lockf: 

execute regular expression, 
regular expression, regcmp, 
compile and match routines, 
match routines, regexp: 
regex: compile and execute 
for a common object file, 
ldrseek, ldnrseek: seek to 
common object file, reloc: 
/fmod, fabs: floor, ceiling, 
mod, amod, dmod: Fortran 
unlink: 
clock: 

stream, fseek, rewind, ftell: 
common object file/ ldgetname: 

argument, getarg: 
variable, getenv: 
accounting, mclock: 

abs: 
string, len: 
substring, index: 
logname: 
line arguments, iargc: 
name, getenv: 
stat: data 
file pointer in a/ fseek, 
creat: create a new file or 
chroot: change 
logarithm, power, square 
/dsqrt, csqrt: Fortran square 
common object file access 
expression compile and match 
and, or, xor, not, lshift, 
space allocation, brk, 
formatted input, 
sccsfile: format of 

common object file, 
optimization/ curses: CRT 
inittab: 
bsearch: binary 


putw: put character or word on 

qsort: quicker sort 

queue 

quicker sort 

rand, srand: random-number . 

rand, srand: simple 

random-number generator. . . 
random-number generator. . . 

read a password 

read an indexed symbol table 
read an indexed/named section 

read from file 

read: read from file 

read the archive header of a . 
read the file header of a ... 
reading, ldopen, ldaopen: . . 

reading or writing 

read/write file pointer. . . . 
real, float, sngl, dble, .... 
realloc, calloc: main memory . 
realloc, calloc, mallopt, . . . 
receipt of a signal, signal: . . 
receipt of a system signal. . . 
record locking on files. . . . 
regcmp, regex: compile and 
regex: compile and execute 
regexp: regular expression . . 
regular expression compile and 
regular expression, regcmp, 
reloc: relocation information . 
relocation entries of a/ ... 
relocation information for a 
remainder, absolute value/ . . 
remaindering intrinsic/ . . . 
remove directory entry. . . . 
report CPU time used. . . . 
reposition a file pointer in a 
retrieve symbol name for . . 
return Fortran command-line 
return Fortran environment 

return Fortran time 

return integer absolute value, 
return length of Fortran . . . 
return location of Fortran . . 
return login name of user. . . 
return the number of command 
return value for environment . 
returned by stat system call. . 
rewind, ftell: reposition a . . 
rewrite an existing one. . . . 

root directory 

root functions, /exponential, . 
root intrinsic function. . . . 

routines, ldfcn: 

routines, regexp: regular . . 
rshift: Fortran bitwise/ . . . 
sbrk: change data segment . . 
scanf, fscanf, sscanf: convert . 

SCCS file 

sccsfile: format of SCCS file. . 
scnhdr: section header for a 
screen handling and .... 
script for the init process. . . 
search a sorted table 


putc(3S) 
qsort (3C) 
msgget (2) 
qsort (3 C) 
rand (3 F) 
rand(3C) 
rand(3C) 
rand (3 F) 
getpass(3C) 
ldtbread (3X) 
ldshread (3X) 
read (2) 
read (2) 
ldahread (3X) 
ldfhread (3X) 
ldopen (3X) 
open (2) 
lseek (2) 
ftype(3F) 
malloc(3C) 
malloc(3X) 
signal(2) 
signal(3F) 
lockf(3C) 
regcmp (3X) 
regcmp (3X) 
regexp (5) 
regexp (5) 
regcmp (3X) 
reloc (4) 
ldrseek(3X) 
reloc (4) 
floor (3 M) 
mod(3F) 
unlink(2) 
clock (3C) 
fseek(3S) 
ldgetname(3X) 
getarg (3 F) 
getenv (3 F) 
mclock (3 F) 
abs(3C) 
len(3F) 
index (3 F) 
logname(3X) 
iargc (3 F) 
getenv (3C) 
stat (5) 
fseek (3S) 
creat(2) 
chroot (2) 
exp(3M) 
sqrt(3F) 
ldfcn (4) 
regexp (5) 
bool (3 F) 
brk (2) 
scanf(3S) 
sccsfile (4) 
sccsfile (4) 
scnhdr(4) 
curses(3X) 
inittab(4) 
bsearch (3C) 
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lsearch, Ifind: linear 
hcreate, hdestroy: manage hash 
tdelete, twalk: manage binary 
object file, scnhdr: 
object/ /read an indexed/named 
/to line number entries of a 
/to relocation entries of a 
/seek to an indexed/named 
/mrand48, jrand48, srand48, 
section of/ ldsseek, ldnsseek: 
a section/ ldlseek, ldnlseek: 
a section/ ldrseek, ldnrseek: 
header of a common/ ldohseek: 
common object file, ldtbseek: 
shmget: get shared memory 
brk, sbrk: change data 
semctl: 
semop: 
semget: get set of 
operations. 

a group of processes, kill: 
buffering to a stream. 

IDs. setuid, 
getgrent, getgrgid, getgrnam, 
goto. 

hashing encryption, crypt, 

getpwent, getpwuid, getpwnam, 
gettydefs: speed and terminal 
group IDs. 
/getutid, getutline, pututline, 
stream, setbuf, 
data in a/ sputl, 
operations, shmctl: 

shmop: 
shmget: get 
system: issue a 
system: issue a 
operations. 

segment, 
operations, 
transfer-of-sign intrinsic/ 
pause: suspend process until 
what to do upon receipt of a 
action on receipt of a system 
on receipt of a system/ 
upon receipt of a signal, 
of processes, kill: send a 
ssignal, gsignal: software 
generator, rand, srand: 
atan, atan2: trigonometric/ 
intrinsic function, 
sin, dsin, csin: Fortran 
/dsinh: Fortran hyperbolic 
functions, 
hyperbolic sine intrinsic/ 
interval. 

current/ ttyslot: find the 
int, ifix, idint, real, float, 
ssignal, gsignal: 
qsort: quicker 
bsearch: binary search a 


search and update 

search tables, hsearch, . . . 
search trees, tsearch, tfind, 
section header for a common . 
section header of a common 
section of a common object/ . 
section of a common object/ . 
section of a common object/ . 
seed48, lcong48: generate/ . . 
seek to an indexed/named . . 
seek to line number entries of 
seek to relocation entries of 
seek to the optional file ... 
seek to the symbol table of a . 

segment 

segment space allocation. . . 
semaphore control operations. 

semaphore operations 

semaphores 

semctl: semaphore control . . 
semget: get set of semaphores, 
semop: semaphore operations, 
send a signal to a process or . 
setbuf, setvbuf: assign .... 
setgid: set user and group . . 
setgrent, endgrent, fgetgrent:/ 
setjmp, longjmp: non-local . . 
setkey, encrypt: generate . . 
setpgrp: set process group ID. 
setpwent, endpwent, fgetpwent:/ 
settings used by getty. . . . 
setuid, setgid: set user and . . 
setutent, endutent, utmpname:/ 
setvbuf: assign buffering to a . 
sgetl: access long integer . . 
shared memory control . . . 
shared memory operations, 
shared memory segment. . . 
shell command from Fortran. 

shell command 

shmctl: shared memory control 
shmget: get shared memory 
shmop: shared memory . . . 
sign, isign, dsign: Fortran . . 

signal 

signal, signal: specify .... 
signal, /specify Fortran . . . 
signal: specify Fortran action 
signal: specify what to do 
signal to a process or a group 

signals 

simple random-number . . . 
sin, cos, tan, asin, acos, . . . 
sin, dsin, csin: Fortran sine 
sine intrinsic function. . . . 
sine intrinsic function. . . . 
sinh, cosh, tanh: hyperbolic 

sinh, dsinh: Fortran 

sleep: suspend execution for 
slot in the utmp file of the . . 
sngl, dble, cmplx, dcmplx,/ 

software signals 

sort 

sorted table 


lsearch (3C) 
hsearch (3C) 
tsearch (3 C) 
scnhdr (4) 
ldshread(3X) 
ldlseek (3X) 
ldrseek (3X) 
ldsseek (3X) 
drand48(3C) 
ldsseek (3X) 
ldlseek(3X) 
ldrseek (3X) 
ldohseek (3X) 
ldtbseek (3X) 
shmget (2) 
brk (2) 
semctl (2) 
semop(2) 
semget (2) 
semctl (2) 
semget (2) 
semop (2) 
kill (2) 
setbuf(3S) 
setuid (2) 
getgrent (3C) 
setjmp (3C) 
crypt (3C) 
setpgrp (2) 
getpwent (3C) 
gettydefs (4) 
setuid (2) 
getut(3C) 
setbuf(3S) 
sputl (3X) 
shmctl (2) 
shmop (2) 
shmget (2) 
system (3 F) 
system (3S) 
shmctl(2) 
shmget (2) 
shmop(2) 
sign(3F) 
pause (2) 
signal (2) 
signal(3F) 
signal (3 F) 
signal (2) 
kill (2) 
ssignal (3C) 
rand(3C) 
trig(3M) 
sin(3F) 
sin(3F) 
sinh(3F) 
sinh(3M) 
sinh(3F) 
sleep(3C) 
ttyslot(3C) 
ftype(3F) 
ssignal (3C) 
qsort (3C) 
bsearch (3C) 
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brk, sbrk: change data segment space allocation brk(2) 

sys3b: machine specific function sys3b(2) 

fspec: format specification in text files fspec(4) 

receipt of a system/ signal: specify Fortran action on signal (3 F) 

receipt of a signal, signal: specify what to do upon signal (2) 

used by getty. gettydefs: speed and terminal settings gettydefs(4) 

output, printf, fprintf, sprintf: print formatted printf(3S) 

integer data in a/ sputl, sgetl: access long sputl(3X) 

square root intrinsic/ sqrt, dsqrt, csqrt: Fortran sqrt(3F) 

power,/ exp, log, log 10, pow, sqrt: exponential, logarithm, exp(3M) 

exponential, logarithm, power, square root functions, /sqrt: exp(3M) 

sqrt, dsqrt, csqrt: Fortran square root intrinsic/ sqrt (3 F) 

generator, irand, rand, srand: random-number rand (3 F) 

generator, rand, srand: simple random-number rand(3C) 

/nrand48, mrand48, jrand48, srand48, seed48, lcong48:/ drand48(3C) 

input, scanf, fscanf, sscanf: convert formatted scanf(3S) 

signals, ssignal, gsignal: software ssignal(3C) 

package, stdio: standard buffered input/output stdio(3S) 

communication package, ftok: standard interprocess stdipc(3C) 

system call, stat: data returned by stat stat(5) 

stat, fstat: get file status stat (2) 

stat: data returned by stat system call stat (5) 

ustat: get file system statistics ustat(2) 

feof, clearerr, fileno: stream status inquiries, ferror, ferror(3S) 

stat, fstat: get file status stat (2) 

input/output package, stdio: standard buffered stdio(3S) 

stime: set time stime(2) 

wait for child process to stop or terminate, wait: wait (2) 

strncmp, strcpy, strncpy,/ strcat, strncat, strcmp, string (3C) 

/strcpy, strncpy, strlen, strchr, strrchr, strpbrk,/ string(3C) 

strncpy,/ strcat, strncat, strcmp, strncmp, strcpy, string (3C) 

/strncat, strcmp, strncmp, strcpy, strncpy, strlen,/ string (3C) 

/strrchr, strpbrk, strspn, strcspn, strtok: string/ string(3C) 

ffiush: close or flush a stream, fclose, fclose(3S) 

fopen, freopen, fdopen: open a stream fopen(3S) 

reposition a file pointer in a stream, fseek, rewind, ftell: fseek(3S) 

get character or word from a stream, /getchar, fgetc, getw: getc(3S) 

fgets: get a string from a stream, gets, gets(3S) 

put character or word on a stream, /putchar, fputc, putw: putc(3S) 

puts, fputs: put a string on a stream puts(3S) 

setvbuf: assign buffering to a stream, setbuf, setbuf(3S) 

/feof, clearerr, fileno: stream status inquiries ferror (3S) 

push character back into input stream, ungetc: ungetc(3S) 

long integer and base-64 ASCII string. /164a: convert between a641(3C) 

lge, lgt, lie, lit: string comparison intrinsic/ strcmp (3 F) 

convert date and time to string, /asctime, tzset: ctime(3C) 

floating-point number to string, /fcvt, gcvt: convert ecvt(3C) 

gps: graphical primitive string, format of graphical/ gps(4) 

gets, fgets: get a string from a stream gets(3S) 

len: return length of Fortran string len(3F) 

puts, fputs: put a string on a stream puts(3S) 

strspn, strcspn, strtok: string operations, /strpbrk, string (3C) 

number, strtod, atof: convert string to double-precision strtod(3C) 

strtol, atol, atoi: convert string to integer strtol(3C) 

/strncmp, strcpy, strncpy, strlen, strchr, strrchr,/ string (3C) 

strcpy, strncpy,/ strcat, strncat, strcmp, strncmp, string (3C) 

strcat, strncat, strcmp, strncmp, strcpy, strncpy,/ string (3 C) 

/strcmp, strncmp, strcpy, strncpy, strlen, strchr,/ string (3C) 

/strlen, strchr, strrchr, strpbrk, strspn, strcspn,/ string (3 C) 

/strncpy, strlen, strchr, strrchr, strpbrk, strspn,/ string (3C) 

/strchr, strrchr, strpbrk, strspn, strcspn, strtok:/ string (3C) 

to double-precision number, strtod, atof: convert string strtod (3C) 

/strpbrk, strspn, strcspn, strtok: string operations string (3C) 

string to integer, strtol, atol, atoi: convert strtol (3C) 
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intro: introduction to 
/intrinsic functions and 
plot: graphics interface 
return location of Fortran 
sync: update 
interval, sleep: 
pause: 

swab: 

file/ ldgetname: retrieve 
name for common object file 
object/ /compute the index of a 
ldtbread: read an indexed 
syms: common object file 
object/ ldtbseek: seek to the 
symbol table format. 

function, 
error/ perror, errno, 
perror, errno, sys_errlist, 
profile: 

binary search a sorted 
for common object file symbol 
/compute the index of a symbol 
file, /read an indexed symbol 
common object file symbol 
mnttab: mounted file system 
ldtbseek: seek to the symbol 
configuration information 
hdestroy: manage hash search 
trigonometric/ sin, cos, 
intrinsic function, 
tan, dtan: Fortran 
/dtanh: Fortran hyperbolic 
hyperbolic tangent intrinsic/ 
sinh, cosh, 
search trees, tsearch, tfind, 
temporary file, tmpnam, 
tmpfile: create a 
tempnam: create a name for a 
terminals, 
term: format of compiled 
file., 
terminfo: 
generate file name for 
dial: establish an out-going 
getty. gettydefs: speed and 
isatty: find name of a 
term: conventional names for 
abort: 
exit, exit: 
for child process to stop or 
data base, 
fspec: format specification in 
plock: lock process, 
binary search trees, tsearch, 
mclock: return Fortran 

profil: execution 
stime: set 
time: get 
tzset: convert date and 
clock: report CPU 
timezone: set default system 


subroutines and libraries intro (3) 

subroutines., btest, ibset,/ mil(3F) 

subroutines plot(3X) 

substring, index: index (3 F) 

super block sync(2) 

suspend execution for sleep (3C) 

suspend process until signal . pause (2) 

swab: swap bytes swab(3C) 

swap bytes swab(3C) 

symbol name for common object ldgetname (3X) 

symbol table entry, /symbol ldgetname(3X) 

symbol table entry of a common ldtbindex(3X) 

symbol table entry of a common/ ldtbread (3X) 

symbol table format syms (4) 

symbol table of a common ldtbseek (3X) 

syms: common object file syms (4) 

sync: update super block sync(2) 

sys3b: machine specific sys3b(2) 

sys_errlist, sys_nerr: system perror (3C) 

sys nerr: system error/ perror (3 C) 

system-wide user profile profile (4) 

table, bsearch: bsearch(3C) 

table entry, /symbol name ldgetname(3X) 

table entry of a common object/ ldtbindex(3X) 

table entry of a common object ldtbread (3X) 

table format, syms: syms (4) 

table mnttab (4) 

table of a common object file ldtbseek(3X) 

table, system: system system (4) 

tables, hsearch, hcreate hsearch(3C) 

tan, asin, acos, atan, atan2: trig(3M) 

tan, dtan: Fortran tangent tan(3F) 

tangent intrinsic function tan(3F) 

tangent intrinsic function tanh(3F) 

tanh, dtanh: Fortran tanh(3F) 

tanh: hyperbolic functions sinh(3M) 

tdelete, twalk: manage binary tsearch (3C) 

tempnam: create a name for a tmpnam (3S) 

temporary file tmpfile(3S) 

temporary file, tmpnam, tmpnam (3S) 

term: conventional names for term (5) 

term file term (4) 

term: format of compiled term term (4) 

terminal capability data base terminfo(4) 

terminal, ctermid: ctermid(3S) 

terminal line connection dial(3C) 

terminal settings used by gettydefs (4) 

terminal, ttyname, tty name (3C) 

terminals term (5) 

terminate Fortran program abort (3 F) 

terminate process exit (2) 

terminate, wait: wait wait (2) 

terminfo: terminal capability terminfo (4) 

text files fspec (4) 

text, or data in memory plock (2) 

tfind, tdelete, twalk: manage tsearch (3C) 

time accounting mclock (3 F) 

time: get time time (2) 

time profile profil (2) 

time stime (2) 

time time (2) 

time to string, /asctime, ctime(3C) 

time used clock (3C) 

time zone timezone (4) 
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process times, 
get process and child process 
file access and modification 
time zone, 
file. 

for a temporary file, 
/tolower, toupper, tolower, 
popen, pclose: initiate pipe 
toupper, tolower, _toupper, 
toascii: translate/ toupper, 
translate/ toupper, tolower, 
tolower, toascii: translate/ 
ptrace: process 
sign, isign, dsign: Fortran 
/ toupper, tolower, toascii: 

ftw: walk a file 
twalk: manage binary search 
tan, asin, acos, atan, atan2: 
twalk: manage binary search/ 
a terminal, 
utmp file of the current/ 
tsearch, tfind, tdelete, 
ichar, char: explicit Fortran 
types. 

types: primitive system data 
/localtime, gmtime, asctime, 
control, 
getpw: get name from 
limits, 
creation mask. 

UNIX system, 
into input stream. 
/seed48, lcong48: generate 
mktemp: make a 
entry, 
umount: 
lfind: linear search and 
sync: 

setuid, setgid: set 
character login name of the 
/getgid, getegid: get real 
environ: 
ulimit: get and set 
logname: return login name of 
profile: system-wide 
/get real user, effective 
the utmp file of the current 
statistics, 
modification times, 
utmp, wtmp: 
endutent, utmpname: access 
ttyslot: find the slot in the 
entry formats, 
/pututline, setutent, endutent, 
abs: return integer absolute 
cabs, zabs: Fortran absolute 
getenv: return 
ceiling, remainder, absolute 
putenv: change or add 
values. 

values: machine-dependent 
/print formatted output of a 
/print formatted output of a 


times: get process and child times (2) 

times, times: times (2) 

times, utime: set utime(2) 

timezone: set default system timezone(4) 

tmpfile: create a temporary tmpfile(3S) 

tmpnam, tempnam: create a name tmpnam(3S) 

toascii: translate characters conv(3C) 

to/from a process popen (3S) 

tolower, toascii: translate/ conv(3C) 

tolower, toupper, tolower, conv(3C) 

toupper, tolower, toascii: conv(3C) 

toupper, tolower, toupper, conv(3C) 

trace ptrace (2) 

transfer-of-sign intrinsic/ sign(3F) 

translate characters conv(3C) 

tree ftw(3C) 

trees, /tfind, tdelete, tsearch (3C) 

trigonometric functions, /cos, trig (3 M) 

tsearch, tfind, tdelete, tsearch (3C) 

ttyname, isatty: find name of tty name (3C) 

ttyslot: find the slot in the ttyslot (3C) 

twalk: manage binary search/ tsearch (3C) 

type conversion, /dcmplx ftype(3F) 

types: primitive system data types (5) 

types types (5) 

tzset: convert date and time/ ctime(3C) 

uadmin: administrative uadmin(2) 

UID getpw (3C) 

ulimit: get and set user ulimit (2) 

umask: set and get file umask(2) 

umount: unmount a file system umount (2) 

uname: get name of current uname(2) 

ungetc: push character back ungetc(3S) 

uniformly distributed/ drand48(3C) 

unique file name mktemp(3C) 

unlink: remove directory unlink (2) 

unmount a file system umount (2) 

update, lsearch, lsearch(3C) 

update super block sync (2) 

user and group IDs setuid (2) 

user, cuserid: get cuserid(3S) 

user, effective user, real/ getuid(2) 

user environment environ (5) 

user limits ulimit (2) 

user logname (3X) 

user profile profile (4) 

user, real group, and/ getuid(2) 

user, /find the slot in ttyslot (3C) 

ustat: get file system ustat(2) 

utime: set file access and utime (2) 

utmp and wtmp entry formats utmp(4) 

utmp file entry, /setutent, getut(3C) 

utmp file of the current user ttyslot (3C) 

utmp, wtmp: utmp and wtmp utmp(4) 

utmpname: access utmp file/ getut(3C) 

value abs(3C) 

value, abs, iabs, dabs, abs(3F) 

value for environment name getenv(3C) 

value functions, /fabs: floor, floor (3 M) 

value to environment putenv(3C) 

values: machine-dependent values (5) 

values values(5) 

varargs argument list vprintf(3S) 

varargs argument list vprintf(3X) 
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argument list, varargs: handle variable varargs(5) 

varargs: handle variable argument list varargs (5) 

return Fortran environment variable, getenv: getenv(3F) 

option letter from argument vector, getopt: get getopt(3C) 

assert: verify program assertion assert (3X) 

formatted output of/ vprintf, vfprintf, vsprintf: print vprintf(3S) 

formatted output of/ vprintf, vfprintf, vsprintf: print vprintf(3X) 

file system: format of system volume fs(4) 

print formatted output of a/ vprintf, vfprintf, vsprintf: vprintf(3S) 

print formatted output of a/ vprintf, vfprintf, vsprintf: vprintf(3X) 

output of/ vprintf, vfprintf, vsprintf: print formatted vprintf(3S) 

output of/ vprintf, vfprintf, vsprintf: print formatted vprintf(3X) 

or terminate, wait: wait for child process to stop wait (2) 

to stop or terminate, wait: wait for child process wait (2) 

ftw: walk a file tree ftw(3C) 

signal, signal: specify what to do upon receipt of a signal (2) 

chdir: change working directory chdir(2) 

get path-name of current working directory, getcwd: getcwd(3C) 

write: write on a file write (2) 

putpwent: write password file entry putpwent(3C) 

write: write on a file write(2) 

open: open for reading or writing open (2) 

utmp, wtmp: utmp and wtmp entry formats utmp(4) 

formats, utmp, wtmp: utmp and wtmp entry utmp (4) 

Fortran bitwise/ and, or, xor, not, lshift, rshift: bool (3 F) 

jO, jl, jn, yO, yl, yn: Bessel functions bessel(3M) 

jO, jl, jn, yO, yl, yn: Bessel functions bessel(3M) 

jO, jl, jn, yO, yl, yn: Bessel functions bessel(3M) 

abs, iabs, dabs, cabs, zabs: Fortran absolute value abs(3F) 

set default system time zone, timezone: timezone(4) 
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NAME 

intro — introduction to system calls and error numbers 

SYNOPSIS 

#include <errno.h> 

DESCRIPTION 

This section describes all of the system calls. Most of these calls have one or 
more error returns. An error condition is indicated by an otherwise impossible 
returned value. This is almost always —1; the individual descriptions specify 
the details. An error number is also made available in the external variable 
errno. Errno is not cleared on successful calls, so it should be tested only after 
an error has been indicated. 

Each system call description attempts to list all possible error numbers. The 
following is a complete list of the error numbers and their names as defined in 

<errno.h>. 

1 EPERM Not owner 

Typically this error indicates an attempt to modify a file in some way 
forbidden except to its owner or super-user. It is also returned for 
attempts by ordinary users to do things allowed only to the super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file should exist 
but doesn’t, or when one of the directories in a path name does not 
exist. 

3 ESRCH No such process 

No process can be found corresponding to that specified by pid in kill 
or ptrace. 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which the user has 
elected to catch, occurred during a system call. If execution is 
resumed after processing the signal, it will appear as if the interrupted 
system call returned this error condition. 

5 EIO I/O error 

Some physical I/O error has occurred. This error may in some cases 
occur on a call following the one to which it actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not exist, or 
beyond the limits of the device. It may also occur when, for example, 
a tape drive is not on-line or no disk pack is loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 5,120 bytes is presented to a member of 
the exec family. 

8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has the appropri- 
ate permissions, does not start with a valid magic number (see 
a.out( 4)). 

9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a read (respectively, 
write) request is made to a file which is open only for writing (respec- 
tively, reading). 

10 ECHILD No child processes 

A wait was executed by a process that had no existing or unwaited-for 
child processes. 
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1 1 EAGAIN No more processes 

A fork failed because the system’s process table is full or the user is 
not allowed to create any more processes. 

1 2 ENOMEM Not enough space 

During an exec, brk, or sbrk, a program asks for more space than the 
system is able to supply. This is not a temporary condition; the max- 
imum space size is a system parameter. The error may also occur if 
the arrangement of text, data, and stack segments requires too many 
segmentation registers, or if there is not enough swap space during a 
fork. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the protec- 
tion system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to use an argu- 
ment of a system call. 

1 5 ENOTBLK Block device required 

A non-block file was mentioned where a block device was required, 
e.g., in mount. 

16 EBUSY Device or resource busy 

An attempt was made to mount a device that was already mounted or 
an attempt was made to dismount a device on which there is an active 
file (open file, current directory, mounted-on file, active text segment). 
It will also occur if an attempt is made to enable accounting when it is 
already enabled. The device or resource is currently unavailable. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, e.g., link. 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a dev- 
ice; e.g., read a write-only device. 

20 ENOTDIR Not a directory 

A non-directory was specified where a directory is required, for exam- 
ple in a path prefix or as an argument to chdiri 2). 

21 EISDIR Is a directory 

An attempt was made to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a non-mounted device; men- 
tioning an undefined signal in signal, or kill; reading or writing a file 
for which Iseek has generated a negative pointer). Also set by the 
math functions described in the (3M) entries of this manual. 

23 ENFILE File table overflow 

The system file table is full, and temporarily no more opens can be 
accepted. 

24 EMFILE Too many open files 

No process may have more than 20 file descriptors open at a time. 
When a record lock is being created with fcntl, there are too many files 
with record locks on them. 

25 ENOTTY Not a character device 

An attempt was made to ioctl(, 2) a file that is not a special character 
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device. 

26 ETXTBSY Text file busy 

An attempt was made to execute a pure-procedure program that is 
currently open for writing. Also an attempt to open for writing a 
pure-procedure program that is being executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum file size (1,082,201,088 bytes) 
or ULIMIT; see ulimiti 2). 

28 ENOSPC No space left on device 

During a write to an ordinary file, there is no free space left on the 
device. In fcntl, the setting or removing of record locks on a file can- 
not be accomplished because there are no more record entries left on 
the system. 

29 ESPIPE Illegal seek 

An Iseek was issued to a pipe. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a device 
mounted read-only. 

31 EMLINK Too many links 

An attempt to make more than the maximum number of links (1000) 
to a file. 

32 EPIPE Broken pipe 

A write on a pipe for which there is no process to read the data. This 
condition normally generates a signal; the error is returned if the signal 
is ignored. 

33 EDOM Math argument 

The argument of a function in the math package (3M) is out of the 
domain of the function. 

34 ERANGE Result too large 

The value of a function in the math package (3M) is not representable 
within machine precision. 

35 ENOMSG No message of desired type 

An attempt was made to receive a message of a type that does not 
exist on the specified message queue; see msgopil). 

36 EIDRM Identifier Removed 

This error is returned to processes that resume execution due to the 
removal of an identifier from the file system’s name space (see 
msgctli 2), semctl(2), and shmctl(2)) . 

45 EDEADLK Deadlock 

A deadlock situation was detected and avoided. 

Definitions 

Process ID Each active process in the system is uniquely identified by a positive 
integer called a process ID. The range of this ID is from 1 to 30,000. 

Parent Process ID A new process is created by a currently active process; see 
fork (2) . The parent process ID of a process is the process ID of its creator. 

Process Group ID Each active process is a member of a process group that is 
identified by a positive integer called the process group ID. This ID is the pro- 
cess ID of the group leader. This grouping permits the signaling of related 
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processes; see kill (2). 


Tty Group ID Each active process can be a member of a terminal group that is 
identified by a positive integer called the tty group ID. This grouping is used to 
terminate a group of related processes upon termination of one of the processes 
in the group; see exit (2) and signal (2) . 


Real User ID and Real Group ID Each user allowed on the system is identified 
by a positive integer called a real user ID. 

Each user is also a member of a group. The group is identified by a positive 
integer called the real group ID. 

An active process has a real user ID and real group ID that are set to the real 
user ID and real group ID, respectively, of the user responsible for the creation 
of the process. 


Effective User ID and Effective Group ID An active process has an effective 
user ID and an effective group ID that are used to determine file access permis- 
sions (see below). The effective user ID and effective group ID are equal to the 
process’s real user ID and real group ID respectively, unless the process or one 
of its ancestors evolved from a file that had the set-user-ID bit or set-group ID 
bit set; see exec (2). 


Super-user A process is recognized as a super-user process and is granted spe- 
cial privileges if its effective user ID is 0. 

Special Processes The processes with a process ID of 0 and a process ID of 1 are 
special processes and are referred to as procO and prod. 

ProcO is the scheduler. Prod is the initialization process Unit). Procl is the 
ancestor of every other process in the system and is used to control the process 
structure. 

File Descriptor A file descriptor is a small integer used to do I/O on a file. The 
value of a file descriptor is from 0 to 19. A process may have no more than 20 
file descriptors (0-19) open simultaneously. A file descriptor is returned by sys- 
tem calls such as openil), or pipe (2) . The file descriptor is used as an argu- 
ment by calls such as read {2), writei. 2), ioctli 2), and closei.2). 


File Name Names consisting of 1 to 14 characters may be used to name an 
ordinary file, special file or directory. 

These characters may be selected from the set of all character values excluding 
\0 (null) and the ASCII code for / (slash). 

Note that it is generally unwise to use *, ?, [, or J as part of file names because 
of the special meaning attached to these characters by the shell. See sMl). 
Although permitted, it is advisable to avoid the use of unprintable characters in 
file names. 


Path Name and Path Prefix A path name is a null-terminated character string 
starting with an optional slash (/), followed by zero or more directory names 
separated by slashes, optionally followed by a file name. 

More precisely, a path name is a null-terminated character string constructed 
as follows: 
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<path-name>::=<file-name> | <path-prefix> <file-name>|/ 

< path-prefix > ::= < rtprefix> | / < rtprefix> 
<rtprefix>::=<dirname>/| <rtprefix> <dirname>/ 

where <file-name> is a string of 1 to 14 characters other than the ASCII slash 
and null, and <dirname> is a string of 1 to 14 characters (other than the 
ASCII slash and null) that names a directory. 

If a path name begins with a slash, the path search begins at the root direc- 
tory. Otherwise, the search begins from the current working directory. 

A slash by itself names the root directory. 

Unless specifically stated otherwise, the null path name is treated as if it named 
a non-existent file. 

Directory 

Directory entries are called links. By convention, a directory contains at least 
two links, . and referred to as dot and dot -dot respectively. Dot refers to 
the directory itself and dot-dot refers to its parent directory. 


Root Directory and Current Working Directory Each process has associated 
with it a concept of a root directory and a current working directory for the 
purpose of resolving path name searches. The root directory of a process need 
not be the root directory of the root file system. 

File Access Permissions 

Read, write, and execute/search permissions on a file are granted to a process if 
one or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of the owner 
of the file and the appropriate access bit of the “owner” portion (0700) 
of the file mode is set. 

The effective user ID of the process does not match the user ID of the 
owner of the file, and the effective group ID of the process matches the 
group of the file and the appropriate access bit of the “group” portion 
(070) of the file mode is set. 

The effective user ID of the process does not match the user ID of the 
owner of the file, and the effective group ID of the process does not 
match the group ID of the file, and the appropriate access bit of the 
“other” portion (07) of the file mode is set. 

Otherwise, the corresponding permissions are denied. 

Message Queue Identifier A message queue identifier (msqid) is a unique posi- 
tive integer created by a msggetil) system call. Each msqid has a message 
queue and a data structure associated with it. The data structure is referred to 
as msqid_ds and contains the following members: 


struct 

ipc_perm msg_perm; 

/* operation permission struct */ 

ushort 

msg_qnum; 

/* number of msgs on q */ 

ushort 

msg_qbytes; 

/* max number of bytes on q »/ 

ushort 

msgjspid; 

/» pid of last msgsnd operation */ 

ushort 

msgjrpid; 

/* pid of last msgrcv operation */ 

timet 

msgstime; 

/» last msgsnd time */ 

timet 

msgrtime; 

/* last msgrcv time */ 
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time t msgctime; /* last change time */ 

/* Times measured in secs since »/ 

/* 00:00:00 GMT, Jan. 1, 1970 */ 

Msg_perm is an ipc_perm structure that specifies the message operation permis- 
sion (see below). This structure includes the following members: 


ushort 

cuid; 

/* creator user id */ 

ushort 

cgid; 

/* creator group id */ 

ushort 

uid; 

/* user id */ 

ushort 

gid; 

/* group id */ 

ushort 

mode; 

/* r/w permission */ 


msgqnum 

is the number of messages currently on the queue. 
msg_qbytes 

is the maximum number of bytes allowed on the queue. 

msglspid 

is the process id of the last process that performed a msgsnd operation. 

msglrpid 

is the process id of the last process that performed a msgrcv operation. 

msgstime 

is the time of the last msgsnd operation. 

msg_rtime 

is the time of the last msgrcv operation 

msgctime 

is the time of the last msgctl(2) operation that changed a member of 
the above structure. 

Message Operation Permissions In the msgop(2) and msgctl (2) system call 
descriptions, the permission required for an operation is given as "{token}", 
where "token" is the type of permission needed interpreted as follows: 


00400 

Read by user 

00200 

Write by user 

00060 

Read, Write by group 

00006 

Read, Write by others 


Read and Write permissions on a msqid are granted to a process if one or more 
of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches msg_perm.[cluid in the 
data structure associated with msqid and the appropriate bit of the 
“user” portion (0600) of msg_perm.mode is set. 

The effective user ID of the process does not match msg_perm.[c]uid 
and the effective group ID of the process matches msg_perm.[c]gid and 
the appropriate bit of the “group” portion (060) of msg_perm.mode is 
set. 

The effective user ID of the process does not match msg_perm.[c]uid 
and the effective group ID of the process does not match 
msgjerm.Iclgid and the appropriate bit of the “other” portion (06) of 
msg_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 
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Semaphore Identifier A semaphore identifier (semid) is a unique positive 
integer created by a semgetil) system call. Each semid has a set of sema- 
phores and a data structure associated with it. The data structure is referred to 
as semid_ds and contains the following members: 

struct ipc_perm sem_perm; /* operation permission struct */ 

ushort semnsems; /* number of sems in set */ 

time t semotime; /* last operation time */ 

time t sem_ctime; /* last change time */ 

/» Times measured in secs since */ 

/* 00:00:00 GMT, Jan. 1, 1970 */ 

Sem jerm is an ipc_perm structure that specifies the semaphore operation per- 
mission (see below) . This structure includes the following members: 


ushort 

cuid; 

/* creator user id */ 

ushort 

cgid; 

/* creator group id */ 

ushort 

uid; 

/* user id */ 

ushort 

gid; 

/* group id */ 

ushort 

mode; 

/* r/a permission */ 


The value of sem_nsems is equal to the number of semaphores in the set. Each 
semaphore in the set is referenced by a positive integer referred to as a 
semjium. Sem_num values run sequentially from 0 to the value of sem nsems 
minus 1 . Sem_otime is the time of the last semop (2) operation, and sem_ctime 
is the time of the last semctli 2) operation that changed a member of the above 
structure. 


A semaphore is a data structure that contains the following members: 


ushort semval; 
short sempid; 
ushort semncnt; 
ushort semzcnt; 


/« semaphore value */ 

/* pid of last operation »/ 

/* # awaiting semval > cval */ 
/« # awaiting semval = 0 »/ 


Semval is a non-negative integer. Sempid is equal to the process ID of the last 
process that performed a semaphore operation on this semaphore. Semncnt is a 
count of the number of processes that are currently suspended awaiting this 
semaphore’s semval to become greater than its current value. Semzcnt is a 
count of the number of processes that are currently suspended awaiting this 
semaphore’s semval to become zero. 


Semaphore Operation Permissions In the semop (2) and semctli 2) system call 
descriptions, the permission required for an operation is given as "(token)", 
where "token" is the type of permission needed interpreted as follows: 


00400 

Read by user 

00200 

Alter by user 

00060 

Read, Alter by group 

00006 

Read, Alter by others 


Read and Alter permissions on a semid are granted to a process if one or more 
of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches sem_perm.[c]uid in the 
data structure associated with semid and the appropriate bit of the 
“user” portion (0600) of sem_perm.mode is set. 

The effective user ID of the process does not match sem_perm.[c)uid 
and the effective group ID of the process matches sem_perm.lclgid and 
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the appropriate bit of the “group” portion (060) of sem_perm.mode is 
set. 

The effective user ID of the process does not match sem_perm.[c]uid 
and the effective group ID of the process does not match 
sem_perm.[c]gid and the appropriate bit of the “other” portion (06) of 
sem_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 


Shared Memory Identifier A shared memory identifier (shmid) is a unique 
positive integer created by a shmget (2) system call. Each shmid has a segment 
of memory (referred to as a shared memory segment) and a data structure 
associated with it. The data structure is referred to as shmidds and contains 
the following members: 


struct 

ipc_perm shm_perm; 

/* operation permission struct */ 

int 

shmsegsz; 

/* size of segment */ 

ushort 

shm_cpid; 

/* creator pid */ 

ushort 

shmlpid; 

/* pid of last operation */ 

short 

shm_nattch; 

/* number of current attaches */ 

timet 

shmatime; 

/* last attach time */ 

time_t 

shm_dtime; 

/* last detach time */ 

time_t 

shm_ctime; 

/* last change time */ 


/* Times measured in secs since */ 
/« 00:00:00 GMT, Jan. 1, 1970 */ 


Shm_perm is an ipc_perm structure that specifies the shared memory operation 
permission (see below). This structure includes the following members: 


ushort 

cuid; 

/* creator user id «/ 

ushort 

cgid; 

/* creator group id »/ 

ushort 

uid; 

/» user id */ 

ushort 

gid; 

/* group id */ 

ushort 

mode; 

/* r/w permission */ 


Shmsegsz specifies the size of the shared memory segment. Shmcpid is the 
process id of the process that created the shared memory identifier. Shmlpid is 
the process id of the last process that performed a shmop(, 2) operation. 
Shm_nattch is the number of processes that currently have this segment 
attached. Shmatime is the time of the last shmat operation, shm_dtime is the 
time of the last shmdt operation, and shm_ctime is the time of the last 
shmctl (2) operation that changed one of the members of the above structure. 

Shared Memory Operation Permissions In the shmop (2) and shmctl (2) system 
call descriptions, the permission required for an operation is given as ''{token}", 
where "token" is the type of permission needed interpreted as follows: 


00400 

Read by user 

00200 

Write by user 

00060 

Read, Write by group 

00006 

Read, Write by others 


Read and Write permissions on a shmid are granted to a process if one or more 
of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches shm_perm.[c]uid in the 
data structure associated with shmid and the appropriate bit of the 
“user” portion (0600) of shm_perm.mode is set. 
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The effective user ID of the process does not match shm_perm.[c]uid 
and the effective group ID of the process matches shm_perm.[clgid and 
the appropriate bit of the “group” portion (060) of shm_perm.mode is 
set. 

The effective user ID of the process does not match shm_perm.[c]uid 
and the effective group ID of the process does not match 
shm_perm.[c]gid and the appropriate bit of the “other” portion (06) of 
shm_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

SEE ALSO 

close (2), ioctl(2), open (2), pipe (2), read (2), write (2), intro (3). 
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NAME 

access — determine accessibility of a file 
SYNOPSIS 

int access (path, amode) 
char *path; 
int amode; 

DESCRIPTION 

Path points to a path name naming a file. Access checks the named file for 
accessibility according to the bit pattern contained in amode, using the real 
user ID in place of the effective user ID and the real group ID in place of the 
effective group ID. The bit pattern contained in amode is constructed as fol- 
lows: 


04 read 

02 write 

01 execute (search) 

00 check existence of file 


Access to the file is 

[enotdir] 

[enoent] 

[enoent] 

[eacces] 

[erofs] 

[etxtbsy] 

[eaccess] 

[efault] 


denied if one or more of the following are true: 

A component of the path prefix is not a directory. 
Read, write, or execute (search) permission is 
requested for a null path name. 

The named file does not exist. 

Search permission is denied on a component of the 
path prefix. 

Write access is requested for a file on a read-only 
file system. 

Write access is requested for a pure procedure 
(shared text) file that is being executed. 

Permission bits of the file mode do not permit 
the requested access. 

Path points outside the allocated address 
space for the process. 


The owner of a file has permission checked with respect to the “owner” read, 
write, and execute mode bits Members of the file’s group other than the owner 
have permissions checked with respect to the “group” mode bits, and all others 
have permissions checked with respect to the “other” mode bits. 


SEE ALSO 

chmod(2), stat(2). 


DIAGNOSTICS 

If the requested access is permitted, a value of 0 is returned. Otherwise, a 
value of — 1 is returned and errno is set to indicate the error. 


10/84 


- 1 - 


10/84 



ACCT (2) 


ACCT(2) 


NAME 

acct — enable or disable process accounting 

SYNOPSIS 

int acct (path) 
char »path; 


DESCRIPTION 

Acct is used to enable or disable the system process accounting routine. If the 
routine is enabled, an accounting record will be written on an accounting file 
for each process that terminates. Termination can be caused by one of two 
things: an exit call or a signal; see exit (2) and signal (2). The effective user ID 
of the calling process must be super-user to use this call. 

Path points to a path name naming the accounting file. The accounting file 
format is given in acct (4) . 

The accounting routine is enabled if path is non-zero and no errors occur dur- 
ing the system call. It is disabled if path is zero and no errors occur during the 
system call. 


Acct will fail if one or more of the following are true: 


[EPERM] 

[EBUSY] 

[ENOTDIR] 

[ENOENT] 


The effective user of the calling process is not super-user. 

An attempt is being made to enable accounting when it is 
already enabled. 

A component of the path prefix is not a directory. 

One or more components of the accounting file path name do 
not exist. 


[EACCES1 
[EACCES] 
[EACCES] 
[EISDIR] 
[EROFS] 
[EFAULT] 
SEE ALSO 


A component of the path prefix denies search permission. 
The file named by path is not an ordinary file. 

Mode permission is denied for the named accounting file. 
The named file is a directory. 

The named file resides on a read-only file system. 

Path points to an illegal address. 


exit (2), signal (2), acct (4). 


DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

alarm — set a process alarm clock 

SYNOPSIS 

unsigned alarm (sec) 
unsigned sec; 

DESCRIPTION 

Alarm instructs the alarm clock of the calling process to send the signal 
SIGALRM to the calling process after the number of real time seconds specified 
by sec have elapsed; see signal (2). 

Alarm requests are not stacked; successive calls reset the alarm clock of the 
calling process. 

If sec is 0, any previously made alarm request is canceled. 

SEE ALSO 

pause(2), signal (2). 

DIAGNOSTICS 

Alarm returns the amount of time previously remaining in the alarm clock of 
the calling process. 
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NAME 

brk, sbrk — change data segment space allocation 

SYNOPSIS 

int brk (endds) 
char * endds; 

char *sbrk (incr) 
int incr; 

DESCRIPTION 

Brk and sbrk are used to change dynamically the amount of space allocated for 
the calling process’s data segment; see exec (2). The change is made by reset- 
ting the process’s break value and allocating the appropriate amount of space. 
The break value is the address of the first location beyond the end of the data 
segment. The amount of allocated space increases as the break value increases. 
The newly allocated space is set to zero. 

Brk sets the break value to endds and changes the allocated space accordingly. 

Sbrk adds incr bytes to the break value and changes the allocated space 
accordingly. Incr can be negative, in which case the amount of allocated space 
is decreased. 

Brk and sbrk will fail without making any change in the allocated space if one 
or more of the following are true: 

[ENOMEMl Using brk (0) or brkt textaddress) . 

1ENOMEM] Such a change would result in more space being allo- 
cated than is allowed by a system-imposed maximum 
(see ulimiti 2)). 

Such a change would result in the break value being greater than or 
equal to the start address of any attached shared memory segment (see 
shmopil)). 

SEE ALSO 

exec (2), shmop(2), ulimit(2). 

DIAGNOSTICS 

Upon successful completion, brk returns a value of 0 and sbrk returns the old 
break value. Otherwise, a value of —1 is returned and errno is set to indicate 
the error. 
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NAME 

chdir — change working directory 

SYNOPSIS 

int chdir (path) 
char “path; 

DESCRIPTION 

Path points to the path name of a directory. Chdir causes the named directory 
to become the current working directory, the starting point for path searches 
for path names not beginning with /. 

Chdir will fail and the current working directory will be unchanged if one or 
more of the following are true: 

[ENOTDIR] A component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EACCESl Search permission is denied for any component of the path 

name. 

[EFAULT] Path points outside the allocated address space of the process. 

SEE ALSO 

chroot(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

chmod - change mode of file 

SYNOPSIS 

int chmod (path, mode) 
char 'path; 
int mode; 

DESCRIPTION 

Path points to a path name naming a file. Chmod sets the access permission 
portion of the named file’s mode according to the bit pattern contained in 
mode. 

Access permission bits are interpreted as follows: 


04000 Set user ID on execution. 

02000 Set group ID on execution. 

01000 Save text image after execution. 

00400 Read by owner. 

00200 Write by owner. 

00100 Execute (search if a directory) by owner. 

00070 Read, write, execute (search) by group. 

00007 Read, write, execute (search) by others. 

The effective user ID of the process must match the owner of the file or be 
super-user to change the mode of a file. 

If the effective user ID of the process is not super-user, mode bit 01000 (save 
text image on execution) is cleared. 


If the effective user ID of the process is not super-user and the effective group 
ID of the process does not match the group ID of the file, mode bit 02000 (set 
group ID on execution) is cleared. 

If an executable file is prepared for sharing then mode bit 01000 prevents the 
system from abandoning the swap-space image of the program-text portion of 
the file when its last user terminates. Thus, when the next user of the file exe- 
cutes it, the text need not be read from the file system but can simply be 
swapped in, saving time. 

Chmod will fail and the file mode will be unchanged if one or more of the fol- 
lowing are true: 


[ENOTDIR] 

[ENOENT] 

[EACCES] 

[EPERM] 

[EROFS] 
[EFAULT] 
SEE ALSO 


A component of the path prefix is not a directory. 

The named file does not exist. 

Search permission is denied on a component of the path 
prefix. 

The effective user ID does not match the owner of the file and 
the effective user ID is not super-user. 

The named file resides on a read-only file system. 

Path points outside the allocated address space of the process. 


chown(2), mknod(2). 


DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

chown — change owner and group of a file 
SYNOPSIS 

int chown (path, owner, group) 

char ® path; 

int owner, group; 


DESCRIPTION 

Path points to a path name naming a file. The owner ID and group ID of the 
named file are set to the numeric values contained in owner and group respec- 
tively. 

Only processes with effective user ID equal to the file owner or super-user may 
change the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID and set- 
group-ID bits of the file mode, 04000 and 02000 respectively, will be cleared. 

Chown will fail and the owner and group of the named file will remain 
unchanged if one or more of the following are true: 


[ENOTDIR] 

[ENOENT] 

[EACCES] 

[EPERM] 

[EROFSl 
[EFAULTl 
SEE ALSO 


A component of the path prefix is not a directory. 

The named file does not exist. 

Search permission is denied on a component of the path 
prefix. 

The effective user ID does not match the owner of the file and 
the effective user ID is not super-user. 

The named file resides on a read-only file system. 

Path points outside the allocated address space of the process. 


chmod(2). 

chown(l) in the 3B2 Computer System User Reference Manual. 


DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

chroot - change root directory 

SYNOPSIS 

int chroot (path) 
char 'path; 

DESCRIPTION 

Path points to a path name naming a directory. Chroot causes the named 
directory to become the root directory, the starting point for path searches for 
path names beginning with /. The user’s working directory is unaffected by the 
chroot system call. 

The effective user ID of the process must be super-user to change the root 
directory. 

The .. entry in the root directory is interpreted to mean the root directory itself. 
Thus, .. cannot be used to access files outside the subtree rooted at the root 
directory. 

Chroot will fail and the root directory will remain unchanged if one or more of 
the following are true: 

[ENOTDIR] Any component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EPERM] The effective user ID is not super-user. 

[EFAULTl Path points outside the allocated address space of the process. 

SEE ALSO 

chdir(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

close — close a file descriptor 

SYNOPSIS 

int close (Aides) 
int Hides; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe sys- 
tem call. Close closes the file descriptor indicated by fildes. All outstanding 
record locks owned by the process (on the file indicated by fildes ) are removed. 

Close will fail if fildes is not a valid open file descriptor. 

SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), open(2), pipe(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

creat - create a new file or rewrite an existing one 

SYNOPSIS 

int creat (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

Creat creates a new ordinary file or prepares to rewrite an existing file named 
by the path name pointed to by path. 

If the file exists, the length is truncated to 0 and the mode and owner are 
unchanged. Otherwise, the file’s owner ID is set to the effective user ID, of the 
process the group ID of the process is set to the effective group ID, of the pro- 
cess and the low-order 12 bits of the file mode are set to the value of mode 
modified as follows: 

All bits set in the process’s file mode creation mask are cleared. See 
umask(2). 

The “save text image after execution bit” of the mode is cleared. See 
chmod (2) . 

Upon successful completion, the file descriptor is returned and the file is open 
for writing, even if the mode does not permit writing. The file pointer is set to 
the beginning of the file. The file descriptor is set to remain open across exec 
system calls. See fcntli 2). No process may have more than 20 files open 
simultaneously. A new file may be created with a mode that forbids writing. 

Creat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EACCES] Search permission is denied on a component of the path 
prefix. 

[ENOENT] The path name is null. 

[EACCES] The file does not exist and the directory in which the file is to 
be created does not permit writing. 

[EROFS] The named file resides or would reside on a read-only file sys- 

tem. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being 
executed. 

[EACCES] The file exists and write permission is denied. 

[EISDIR] The named file is an existing directory. 

[EMFILE] Twenty (20) file descriptors are currently open. 

[EFAULT] Path points outside the allocated address space of the process. 

[ENFILE] The system file table is full. 

SEE ALSO 

chmod (2), close (2), dup(2), fcntl(2), lseek(2), open (2), read (2), umask(2), 
write (2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely the file descriptor, 
is returned. Otherwise, a value of —1 is returned and errno is set to indicate 
the error. 
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NAME 

dup — duplicate an open file descriptor 

SYNOPSIS 

int dup (Aides) 
int Aides; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe sys- 
tem call. Dup returns a new file descriptor having the following in common 
with the original: 

Same open file (or pipe). 

Same file pointer (i.e., both file descriptors share one file pointer). 

Same access mode (read, write or read/write) . 

The new file descriptor is set to remain open across exec system calls. See 
fcntl (2) . 

The file descriptor returned is the lowest one available. 

Dup will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] Twenty (20) file descriptors are currently open. 

SEE ALSO 

creat (2), close (2), exec (2), fcntl (2), open (2), pipe (2). 

DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 
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NAME 

execl, execv, execle, execve, execlp, execvp — execute a file 
SYNOPSIS 

int execl (path, argO, argl, argn, 0) 
char *path, *arg0, *argl, *argn; 

int execv (path, argv) 
char *path, -argv! ]; 

int execle (path, argO, argl, ..., argn, 0, envp) 
char *path, *argO, *argl, ..., *argn, *envpl J; 

int execve (path, argv, envp) 
char *path, «argv[ I, *envp[ 1; 

int execlp (file, argO, argl, ..., argn, 0) 
char »file, *argO, *argl, ..., *argn; 

int execvp (file, argv) 
char *file, »argv[ ]; 

DESCRIPTION 

Exec in all its forms transforms the calling process into a new process. The 
new process is constructed from an ordinary, executable file called the new pro- 
cess file. This file consists of a header (see a.outl 4)), a text segment, and a 
data segment. The data segment contains an initialized portion and an unini- 
tialized portion (bss). There can be no return from a successful exec because 
the calling process is overlaid by the new process. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 
int argc; 

char »*argv, **envp; 

where argc is the argument count and argv is an array of character pointers to 
the arguments themselves. As indicated, argc is conventionally at least one and 
the first member of the array points to a string containing the name of the file. 

Path points to a path name that identifies the new process file. 

File points to the new process file. The path prefix for this file is obtained by a 
search of the directories passed as the environment line "PATH ='' (see 
environ { 5)). The environment is supplied by the shell (see sh{\)). 

ArgO , argl, ..., argn are pointers to null-terminated character strings. These 
strings constitute the argument list available to the new process. By conven- 
tion, at least argO must be present and point to a string that is the same as 
path (or its last component). 

Argv is an array of character pointers to null-terminated strings. These strings 
constitute the argument list available to the new process. By convention, argv 
must have at least one member, and it must point to a string that is the same 
as path (or its last component) . Argv is terminated by a null pointer. 

Envp is an array of character pointers to null-terminated strings. These strings 
constitute the environment for the new process. Envp is terminated by a null 
pointer. For execl and execv, the C run-time start-off routine places a pointer 
to the environment of the calling process in the global cell: 

extern char **environ; 

and it is used to pass the environment of the calling process to the new process. 

File descriptors open in the calling process remain open in the new process, 
except for those whose close-on-exec flag is set; see fcntlll). For those file 
descriptors that remain open, the file pointer is unchanged. 
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Signals set to terminate the calling process will be set to terminate the new pro- 
cess. Signals set to be ignored by the calling process will be set to be ignored 
by the new process. Signals set to be caught by the calling process will be set 
to terminate new process; see signal { 2). 

If the set-user-ID mode bit of the new process file is set (see chmod(2)), exec 
sets the effective user ID of the new process to the owner ID of the new process 
file. Similarly, if the set-group-ID mode bit of the new process file is set, the 
effective group ID of the new process is set to the group ID of the new process 
file. The real user ID and real group ID of the new process remain the same as 
those of the calling process. 

The shared memory segments attached to the calling process will not be 
attached to the new process (see shmopti)). 

Profiling is disabled for the new process; see profit (2) . 

The new process also inherits the following attributes from the calling process: 

nice value (see nice (2)) 

process ID 

parent process ID 

process group ID 

semadj values (see semop (2)) 

tty group ID (see exit (2) and signal { 2)) 

trace flag (see ptracei 2) request 0) 

time left until an alarm clock signal (see alarm (, 2)) 

current working directory 

root directory 

file mode creation mask (see umask(2 )) 

file size limit (see ulimiti 2)) 

utime, stime , cutime, and cstime (see times (2)) 

Exec will fail and return to the calling process if one or more of the following 
are true: 

[ENOENTl One or more components of the new process path name of the 
file do not exist. 


[ENOTDIR] 

[EACCES] 

[EACCES] 

[EACCES] 

1ENOEXEC1 

[ETXTBSY] 

[ENOMEMl 

[E2BIG] 

[EFAULT] 


A component of the new process path of the file prefix is not a 
directory. 

Search permission is denied for a directory listed in the new 
process file’s path prefix. 

The new process file is not an ordinary file. 

The new process file mode denies execution permission. 

The exec is not an execlp or execvp, and the new process file 
has the appropriate access permission but an invalid magic 
number in its header. 

The new process file is a pure procedure (shared text) file that 
is currently open for writing by some process. 

The new process requires more memory than is allowed by the 
system-imposed maximum MAXMEM. 

The number of bytes in the new process’s argument list is 
greater than the system-imposed limit of 5120 bytes. 

The new process file is not as long as indicated by the size 
values in its header. 


[EFAULT] Path, argv, or envp point to an illegal address. 
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SEE ALSO 

alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), 

ulimit(2), umask(2), a.out(4), environ(5). 

sh(l) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

If exec returns to the calling process an error has occurred; the return value 
will be —1 and errno will be set to indicate the error. 
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NAME 

exit, _exit — terminate process 

SYNOPSIS 

void exit (status) 
int status; 
void exit (status) 
int status; 

DESCRIPTION 

Exit terminates the calling process with the following consequences: 

All of the file descriptors open in the calling process are closed. 

If the parent process of the calling process is executing a wait, it is 
notified of the calling process’s termination and the low order eight bits 
(i.e., bits 0377) of status are made available to it; see wait (2). 

If the parent process of the calling process is not executing a wait, the 
calling process is transformed into a zombie process. A zombie process 
is a process that only occupies a slot in the process table. It has no 
other space allocated either in user or kernel space. The process table 
slot that it occupies is partially overlaid with time accounting informa- 
tion (see <sys/proc.h>) to be used by times. 

The parent process ID of all of the calling process’s existing child 
processes and zombie processes is set to 1. This means the initializa- 
tion process (see intro { 2)) inherits each of these processes. 

Each attached shared memory segment is detached and the value of 
slun_nattach in the data structure associated with its shared memory 
identifier is decremented by 1. 

For each semaphore for which the calling process has set a semadj 
value (see semopil)), that semadj value is added to the semval of the 
specified semaphore. 

If the process has a process, text, or data lock, an unlock is performed 
(see plock(2)). 

An accounting record is written on the accounting file if the system’s 
accounting routine is enabled; see accti.2). 

If the process ID, tty group ID, and process group ID of the calling pro- 
cess are equal, the SIGHUP signal is sent to each process that has a 
process group ID equal to that of the calling process. 

The C function exit may cause cleanup actions before the process exits. The 
function _exit circumvents all cleanup. 

SEE ALSO 

acct(2), intro (2), plock(2), semop(2), signal(2), wait(2). 

WARNING 

See WARNING in signal (2) . 
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NAME 

fcntl — file control 

SYNOPSIS 

#include <fcntl.h> 

int fcntl (tildes, cmd, arg) 
int tildes, cmd, arg; 

DESCRIPTION 

Fcntl provides for control over open files. Fildes is an open file descriptor 
obtained from a creat, open, dup, fcntl, or pipe system call. 

The commands available are: 

F DUPFD Return a new file descriptor as follows: 

Lowest numbered available file descriptor greater than or 
equal to arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descriptors 
share one file pointer). 

Same access mode (read, write or read/write) . 

Same file status flags (i.e., both file descriptors share the 
same file status flags) . 

The close-on-exec flag associated with the new file descriptor 
is set to remain open across exec (2) system calls. 

F GETFD Get the close-on-exec flag associated with the file descriptor 

fildes. If the low-order bit is 0 the file will remain open 
across exec, otherwise the file will be closed upon execution 
of exec. 

FSETFD Set the close-on-exec flag associated with fildes to the low- 

order bit of arg (0 or 1 as above). 

F GETFL Get file status flags. 

F SETFL Set file status flags to arg. Only certain flags can be set; see 

fcntl (5) . 

F GETLK Get the first lock which blocks the lock description given by 

the variable of type struct flock pointed to by arg. The 
information retrieved overwrites the information passed to 
fcntl in the flock structure. If no lock is found that would 
prevent this lock from being created, then the structure is 
passed back unchanged except for the lock type which will 
be set to F UNLCK. 

FSETLK Set or clear a file segment lock according to the variable of 

type struct flock pointed to by arg (see fcntli. 5)). The cmd 
F SETLK is used to establish read (FRDLCK) and write 
(F WRLCK) locks, as well as remove either type of lock 
(FJJNLCK). If a read or write lock cannot be set fcntl will 
return immediately with an error value of —1. 

FSETLKW This cmd is the same as F SETLK except that if a read or 

write lock is blocked by other locks, the process will sleep 
until the segment is free to be locked. 

A read lock prevents any process from write locking the protected area. More 
than one read lock may exist for a given segment of a file at a given time. The 
file descriptor on which a read lock is being placed must have been opened with 
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read access. 

A write lock prevents any process from read locking or write locking the pro- 
tected area. Only one write lock may exist for a given segment of a file at a 
given time. The file descriptor on which a write lock is being placed must have 
been opened with write access. 

The structure flock describes the type (l type), starting offset {l jw hence) , rela- 
tive offset ( Ijtart ), size {l Jen), and process id (1 _pid) of the segment of the 
file to be affected. The process id field is only used with the FGETLK cmd to 
return the value for a blocking lock. Locks may start and extend beyond the 
current end of a file, but may not be negative relative to the beginning of the 
file. A lock may be set to always extend to the end of file by setting l Jen to 
zero (0). If such a lock also has Ijtart set to zero (0), the whole file will be 
locked. Changing or unlocking a segment from the middle of a larger locked 
segment leaves two smaller segments for either end. Locking a segment that is 
already locked by the calling process causes the old lock type to be removed 
and the new lock type to take affect. All locks associated with a file for a given 
process are removed when a file descriptor for that file is closed by that process 
or the process holding that file descriptor terminates. Locks are not inherited 
by a child process in a forki 2) system call. 

Fcntl will fail if one or more of the following are true: 


[EBADF] 

[EMFILE] 

[EINFILE] 

[EINVALl 

[EACCESS] 


[EMFILE] 

[ENOSPC] 


[EDEADLK] 


Fildes is not a valid open file descriptor. 

Cmd is FDUPFD and 20 file descriptors are currently open. 
Cmd is F DUPFD and arg is negative or greater than 20. 

Cmd is F GETLK, FSETLK, or SETLKW and arg or the data 
it points to is not valid. 

Cmd is F SETLK the type of lock (I type) is a read 
(F RDLCK) or write (F WRLCK lock and the segment of a 
file to be locked is already write locked by another process or 
the type is a write lock and the segment of a file to be locked 
is already read or write locked by another process. 

Cmd is F SETLK or FSETLKW, the type of lock is a read or 
write lock and there are no more file locking headers available 
(too many files have segments locked) . 

Cmd is F SETLK or F SETLKW, the type of lock is a read or 
write lock and there are no more file locking headers available 
(too many files have segments locked) or there are no more 
record locks available (too many file segments locked). 

Cmd is F SETLKW, the lock is blocked by some lock from 
another process and sleeping (waiting) for that lock to become 
free. This would cause a deadlock situation. 


SEE ALSO 

close(2), exec(2), open(2), fcntl(5). 


DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 
F DUPFD A new file descriptor. 

F GETFD Value of flag (only the low-order bit is defined) . 

F SETFD Value other than —1. 

F GETFL Value of file flags. 

F SETFL Value other than — 1. 
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F GETLK Value other than —1. 

FJSETLK Value other than -1. 

F SETLKW Value other than -1. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

fork — create a new process 

SYNOPSIS 

int fork 0 

DESCRIPTION 

Fork causes creation of a new process. The new process (child process) is an 
exact copy of the calling process (parent process). This means the child pro- 
cess inherits the following attributes from the parent process: 

environment 

close-on-exec flag (see exec (2)) 

signal handling settings (i.e., SIG_DFL, SIG_IGN, function address) 

set-user-ID mode bit 

set-group-ID mode bit 

profiling on/off status 

nice value (see nice (2)) 

all attached shared memory segments (see shmop{2 )) 
process group ID 

tty group ID (see exit (2) and signal (2)) 

trace flag (see ptrace (2) request 0) 

time left until an alarm clock signal (see alarm (.2)) 

current working directory 

root directory 

file mode creation mask (see umask (2)) 
file size limit (see ulimiti 2)) 

The child process differs from the parent process in the following ways: 

The child process has a unique process ID. 

The child process has a different parent process ID (i.e., the process ID 
of the parent process). 

The child process has its own copy of the parent’s file descriptors. 
Each of the child’s file descriptors shares a common file pointer with 
the corresponding file descriptor of the parent. 

All semadj values are cleared (see semop (2)) . 

Process locks, text locks and data locks are not inherited by the child 
(see plock (2)). 

The child process’s utime, stime , cutime, and cstime are set to 0. The 
time left until an alarm clock signal is reset to 0. 

Fork will fail and no child process will be created if one or more of the follow- 
ing are true: 

[EAGAIN] The system-imposed limit on the total number of processes 

under execution would be exceeded. 

[EAGAIN] The system-imposed limit on the total number of processes 
under execution by a single user would be exceeded. 
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SEE ALSO 

exec(2), nice(2), plock(2), ptrace(2), semop(2), shmop(2), signal(2), times(2), 

ulimit(2), umask(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, fork returns a value of 0 to the child process and 
returns the process ID of the child process to the parent process. Otherwise, a 
value of —1 is returned to the parent process, no child process is created, and 
errno is set to indicate the error. 
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NAME 


getpid, getpgrp. 8=^ - 8« P»»» ■ P"*“ ^ ^ ^ 

SYNOPSIS 

int getpid 0 

int getpgrp 0 

int getppid 0 

DESCRI PT;ON returns ^ prQcess ID Qf the calling process. 

Getpgrp returns the process group ID of the calling process. 

Getppid returns the parent process ID of the calling process. 

SEE AL exec(2), fork(2), intro(2), setpgrp(2), signal©. 


10/84 


10/84 



GETUID (2) 


GETUID (2) 


NAME 

getuid, geteuid, getgid, getegid — get real user, effective user, real group, and 
effective group IDs 

SYNOPSIS 

unsigned short getuid 0 
unsigned short geteuid 0 
unsigned short getgid 0 
unsigned short getegid () 

DESCRIPTION 

Getuid returns the real user ID of the calling process. 

Geteuid returns the effective user ID of the calling process. 

Getgid returns the real group ID of the calling process. 

Getegid returns the effective group ID of the calling process. 

SEE ALSO 

intro (2), setuid(2). 
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NAME 

ioctl — control device 
SYNOPSIS 

ioctl (tildes, request, arg) 
int Hides, request; 

DESCRIPTION 

Ioctl performs a variety of functions on character special files (devices). The 
write-ups of various devices in Section 7 of the 3B2 Computer System 
Administration Utilities Guide discuss how ioctl applies to them. 

Ioctl will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[ENOTTY] Fildes is not associated with a character special device. 

[EINVAL] Request or arg is not valid. See Section 7 of the UNIX Sys- 
tem V Administrator Reference Manual. 

[EINTR] A signal was caught during the ioctl system call. 

SEE ALSO 

termio(7) in the 3B2 Computer System Administration Utilities Guide. 
DIAGNOSTICS 

If an error has occurred, a value of -1 is returned and errno is set to indicate 
the error. 
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NAME 

kill — send a signal to a process or a group of processes 

SYNOPSIS 

int kill (pid, sig) 
int pid, sig; 

DESCRIPTION 

Kill sends a signal to a process or a group of processes. The process or group 
of processes to which the signal is to be sent is specified by pid. The signal 
that is to be sent is specified by sig and is either one from the list given in sig- 
nal (2), or 0. If sig is 0 (the null signal), error checking is performed but no 
signal is actually sent. This can be used to check the validity of pid. 

The real or effective user ID of the sending process must match the real or 
effective user ID of the receiving process, unless the effective user ID of the 
sending process is super-user. 

The processes with a process ID of 0 and a process ID of 1 are special processes 
(see intro ( 2)) and will be referred to below as procO and prod , respectively. 

If pid is greater than zero, sig will be sent to the process whose process ID is 
equal to pid. Pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and prod whose 
process group ID is equal to the process group ID of the sender. 

If pid is —1 and the effective user ID of the sender is not super-user, sig will be 
sent to all processes excluding procO and prod whose real user ID is equal to 
the effective user ID of the sender. 


If pid is —1 and the effective user ID of the sender is super-user, sig will be 
sent to all processes excluding procO and prod. 

If pid is negative but not — 1, sig will be sent to all processes whose process 
group ID is equal to the absolute value of pid. 


Kill will fail and no signal will be sent if one or more of the following are true: 


[EINVAL] 

[EINVAL] 

[ESRCH] 

[EPERM] 


Sig is not a valid signal number. 

Sig is SIGKILL and pid is 1 (procl). 

No process can be found corresponding to that specified by 
pid. 

The user ID of the sending process is not super-user, and its 
real or effective user ID does not match the real or effective 
user ID of the receiving process. 


SEE ALSO 

getpid(2), setpgrp(2), signal (2). 

kill ( 1 ) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

link — link to a file 


SYNOPSIS 

int link (pathl, path2) 
char *pathl, *path2; 


DESCRIPTION 

Pathl points to a path name naming an existing file. Path2 points to a path 
name naming the new directory entry to be created. Link creates a new link 
(directory entry) for the existing file. 

Link will fail and no link will be created if one or more of the following are 
true: 


[ENOTDIR] 

[ENOENT] 

[EACCES] 

[ENOENT] 

[EEXISTl 

[EPERM] 

[EXDEV] 

[ENOENT] 

[EACCES] 

[EROFS] 

[EFAULT] 

[EMLINK] 

SEE ALSO 

unlink(2). 


A component of either path prefix is not a directory. 

A component of either path prefix does not exist. 

A component of either path prefix denies search permission. 
The file named by path 1 does not exist. 

The link named by path2 exists. 

The file named by pathl is a directory and the effective user 
ID is not super-user. 

The link named by path2 and the file named by pathl are on 
different logical devices (file systems). 

Path2 points to a null path name. 

The requested link requires writing in a directory with a mode 
that denies write permission. 

The requested link requires writing in a directory on a read- 
only file system. 

Path points outside the allocated address space of the process. 
The maximum number of links to a file would be exceeded. 


DIAGNOSTICS . 

Upon successful completion, a value of 0 is returned. Otherwise, a value of 1 
is returned and errno is set to indicate the error. 
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NAME 

lseek — move read/write file pointer 
SYNOPSIS 

long lseek (Hides, offset, whence) 
int Aides; 
long offset; 
int whence; 

DESCRIPTION 

Fildes is a file descriptor returned from a creat, open, dup, or fcntl system call. 
Lseek sets the file pointer associated with fildes as follows: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its current location plus offset. 

If whence is 2, the pointer is set to the size of the file plus offset. 

Upon successful completion, the resulting pointer location, as measured in bytes 
from the beginning of the file, is returned. 

Lseek will fail and the file pointer will remain unchanged if one or more of the 
following are true: 

[EBADF] Fildes is not an open file descriptor. 

[ESPIPE] Fildes is associated with a pipe or fifo. 

[EINVAL and SIGSYS signal] 

Whence is not 0, 1, or 2. 

[EINVAL] The resulting file pointer would be negative. 

Some devices are incapable of seeking. The value of the file pointer associated 
with such a device is undefined. 

SEE ALSO 

creat(2), dup(2), fcntl(2), open(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer indicating the file pointer 
value is returned. Otherwise, a value of — 1 is returned and errno is set to indi- 
cate the error. 
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NAME 

mknod — make a directory, or a special or ordinary file 
SYNOPSIS 

int mknod (path, mode, dev) 
char *path; 
int mode, dev; 


DESCRIPTION 

Mknod creates a new file named by the path name pointed to by path. The 
mode of the new file is initialized from mode. Where the value of mode is 
interpreted as follows: 

0170000 file type; one of the following: 

0010000 fifo special 
0020000 character special 
0040000 directory 
0060000 block special 
0100000 or 0000000 ordinary file 
0004000 set user ID on execution 
0002000 set group ID on execution 
0001000 save text image after execution 
0000777 access permissions; constructed from the following 
0000400 read by owner 
0000200 write by owner 

0000100 execute (search on directory) by owner 
0000070 read, write, execute (search) by group 
0000007 read, write, execute (search) by others 


The owner ID of the file is set to the effective user ID of the process. The 
group ID of the file is set to the effective group ID of the process. 

Values of mode other than those above are undefined and should not be used. 
The low-order 9 bits of mode are modified by the process’s file mode creation 
mask: all bits set in the process’s file mode creation mask are cleared. See 
umask (2) . If mode indicates a block or character special file, dev is a 
configuration-dependent specification of a character or block I/O device. If 
mode does not indicate a block special or character special device, dev is 
ignored. 

Mknod may be invoked only by the super-user for file types other than FIFO 
special. 

Mknod will fail and the new file will not be created if one or more of the fol- 
lowing are true: 


[EPERMl 

[ENOTDIR] 

[ENOENTl 

[EROFS] 


The effective user ID of the process is not super-user. 

A component of the path prefix is not a directory. 

A component of the path prefix does not exist. 

The directory in which the file is to be created is located on a 
read-only file system. 


[EEXIST] The named file exists. 

[EFAULT] Path points outside the allocated address space of the process. 
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SEE ALSO 

chmod(2), exec(2), umask(2), fs(4). 

mkdir(l) in the 3B2 Computer System User Reference Manual. 
DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

mount — mount a file system 
SYNOPSIS 

int mount (spec, dir, rwflag) 
char *spec, »dir; 
int rwflag; 


DESCRIPTION 

Mount requests that a removable file system contained on the block special file 
identified by spec be mounted on the directory identified by dir. Spec and dir 
are pointers to path names. 

Upon successful completion, references to the file dir will refer to the root 
directory on the mounted file system. 

The low-order bit of rwflag is used to control write permission on the mounted 
file system; if 1, writing is forbidden, otherwise writing is permitted according 
to individual file accessibility. 

Mount may be invoked only by the super-user. 

Mount will fail if one or more of the following are true: 


[EPERM] 

[ENOENT] 

[ENOTDIR] 

[ENOTBLK] 

[ENXIO] 

[ENOTDIR] 

[EFAULT] 

[EBUSY] 

[EBUSYl 

[EBUSY] 

[EROFS] 

[ENOSPC] 

[EINVALl 
SEE ALSO 


The effective user ID is not super-user. 

Any of the named files does not exist. 

A component of a path prefix is not a directory. 

Spec is not a block special device. 

The device associated with spec does not exist. 

Dir is not a directory. 

Spec or dir points outside the allocated address space of the 
process. 

Dir is currently mounted on, is someone’s current working 
directory, or is otherwise busy. 

The device associated with spec is currently mounted. 

There are no more mount table entries. 

Spec is write protected and rwflag requests write permission. 

The file system state in the super-block is not FsOKAY and 
rwflag requests write permission. 

The file system magic is not FsMAGIC. 


umount(2), fs (4) . 


DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

msgctl — message control operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/msg.h> 

int msgctl (msqid, cmd, buf) 
int msqid, cmd; 
struct msqid_ds *buf; 


DESCRIPTION 

Msgctl provides a variety of message control operations as specified by cmd. 
The following cmds are available: 

IPC_STAT Place the current value of each member of the data structure 

associated with msqid into the structure pointed to by buf. 
The contents of this structure are defined in intro (2) . (READ) 


IPCSET 


IPC_RMID 


Set the value of the following members of the data structure 
associated with msqid to the corresponding value found in the 
structure pointed to by buf. 
msg_perm.uid 
msg_perm.gid 

msg_perm.mode /* only low 9 bits */ 
msg_qbytes 

This cmd can only be executed by a process that has an 
effective user ID equal to either that of super user or to the 
value of msg_perm.uid in the data structure associated with 
msqid. Only super user can raise the value of msgjjbytes. 

Remove the message queue identifier specified by msqid from 
the system and destroy the message queue and data structure 
associated with it. This cmd can only be executed by a pro- 
cess that has an effective user ID equal to either that of super 
user or to the value of msg_perm.uid in the data structure 
associated with msqid. 


Msgctl will fail if one or more of the following are true: 


[EINVAL] 

[EINVALl 

[EACCES] 

[EPERMl 


[EPERM] 


[EFAULT] 


Msqid is not a valid message queue identifier. 

Cmd is not a valid command. 

Cmd is equal to IPC_STAT and {READ) operation permission 
is denied to the calling process (see intro (.2)). 

Cmd is equal to IPC_RMID or IPCJSET. The effective user ID 
of the calling process is not equal to that of super user and it 
is not equal to the value of msg_perm.uid in the data structure 
associated with msqid. 

Cmd is equal to IPC_SET, an attempt is being made to 
increase to the value of msgjjbytes, and the effective user ID 
of the calling process is not equal to that of super user. 

Buf points to an illegal address. 


SEE ALSO 

intro (2), msgget(2), msgop(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

msgget — get message queue 
SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 

int msgget (key, msgflg) 
key_t key; 
int msgflg; 


DESCRIPTION 

Msgget returns the message queue identifier associated with key. 

A message queue identifier and associated message queue and data structure 
(see intro (2)) are created for key if one of the following are true: 


10 Key is equal to IPC PRIVATE. 

Key does not already have a message queue identifier associated with 
it, and ( msgflg & IPC_CREAT) is “true”. 

Upon creation, the data structure associated with the new message queue 
identifier is initialized as follows: 


Msg_perm.cmd, msg_perm.uid, msg_perm.cgid, and msgjerm.gid are 
set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 
bits of msgflg. 

Msg qnum, msg lspid, msg lrpid, msg stime, and msg rtime are set 
equal to 0. 

Msg ctime is set equal to the current time. 

Msg qbytes is set equal to the system limit. 


Msgget will fail if one or more of the following are true: 

[EACCES] A message queue identifier exists for key, but operation per- 

mission (see intro (.2)) as specified by the low-order 9 bits of 
msgflg would not be granted. 

[ENOENT] A message queue identifier does not exist for key and ( msgflg 
& IPC CREAT) is “false”. 


[ENOSPC1 A message queue identifier is to be created but the system- 

imposed limit on the maximum number of allowed message 
queue identifiers system wide would be exceeded. 

[EEXIST] A message queue identifier exists for key but ( ( msgflg & 

IPC_CREAT) & ( msgflg & IPC_EXCL) ) is “true”. 


SEE ALSO 

intro (2), msgctl(2), msgop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a message queue 
identifier, is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 
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NAME 

msgop — message operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/msg.h> 

int msgsnd (msqid, msgp, msgsz, msgflg) 
int msqid; 

struct msgbuf -msgp; 
int msgsz, msgflg; 

int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz; 
long msgtyp; 
int msgflg; 

DESCRIPTION 

Msgsnd is used to send a message to the queue associated with the message 
queue identifier specified by msqid. (WRITE) Msgp points to a structure con- 
taining the message. This structure is composed of the following members: 

long mtype; /» message type */ 

char mtextU; /* message text */ 

Mtype is a positive integer that can be used by the receiving process for mes- 
sage selection (see msgrcv below/ Mtext is any text of length msgsz bytes. 
Msgsz can range from 0 to a system-imposed maximum. 

Msgflg specifies the action to be taken if one or more of the following are true: 

The number of bytes already on the queue is equal to msg_qbytes (see 
intro (2)). 

The total number of messages on all queues system-wide is equal to the 
system-imposed limit. 

These actions are as follows: 

If ( msgflg & IPC_NOWAIT) is “true”, the message will not be sent and 
the calling process will return immediately. 

If ( msgflg & IPC_NOWAIT) is “false”, the calling process will suspend 
execution until one of the following occurs: 

The condition responsible for the suspension no longer exists, 
in which case the message is sent. 

Msqid is removed from the system (see ms get l (, 2)). When 
this occurs, errno is set equal to EIDRM, and a value of —1 is 
returned. 

The calling process receives a signal that is to be caught. In 
this case the message is not sent and the calling process 
resumes execution in the manner prescribed in signal l 2)). 

Msgsnd will fail and no message will be sent if one or more of the following are 
true: 

[EINVALl Msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process (see 
intro { 2)). 
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[EINVAL] Mtype is less than 1. 

[E AG AIN] The message cannot be sent for one of the reasons cited above 

and (msgflg & IPC_NOWAIT) is “true”. 

[EINVALl Msgsz is less than zero or greater than the system-imposed 

limit. 

[EFAULTl Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to the 
data structure associated with msqid (see intro (2)). 

Msg qnum is incremented by 1. 

Msgjspid is set equal to the process ID of the calling process. 

Msg_stime is set equal to the current time. 

Msgrcv reads a message from the queue associated with the message queue 
identifier specified by msqid and places it in the structure pointed to by msgp. 
(READ} This structure is composed of the following members: 

long mtype; /* message type */ 

char mtextU; /* message text */ 

Mtype is the received message’s type as specified by the sending process. 
Mtext is the text of the message. Msgsz specifies the size in bytes of mtext. 
The received message is truncated to msgsz bytes if it is larger than msgsz and 
(msgflg & MSG_NOERROR) is “true”. The truncated part of the message is 
lost and no indication of the truncation is given to the calling process. 

Msgtyp specifies the type of message requested as follows: 

If msgtyp is equal to 0, the first message on the queue is received. 

If msgtyp is greater than 0, the first message of type msgtyp is 
received. 

If msgtyp is less than 0, the first message of the lowest type that is less 
than or equal to the absolute value of msgtyp is received. 

Msgflg specifies the action to be taken if a message of the desired type is not 
on the queue. These are as follows: 

If (msgflg & IPC_NOWAIT) is “true”, the calling process will return 
immediately with a return value of —1 and errno set to ENOMSG. 

If (msgflg & IPC_NOWAIT) is “false”, the calling process will suspend 
execution until one of the following occurs: 

A message of the desired type is placed on the queue. 

Msqid is removed from the system. When this occurs, errno 
is set equal to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be caught. In 
this case a message is not received and the calling process 
resumes execution in the manner prescribed in signal ( 2)). 

Msgrcv will fail and no message will be received if one or more of the following 
are true: 

[EINVAL] Msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process. 
[EINVAL] Msgsz is less than 0. 

[E2BIG] Mtext is greater than msgsz and (msgflg & MSG_NOERROR) 

is “false”. 
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[ENOMSG] The queue does not contain a message of the desired type and 
imsgtyp & IPC_NOWAIT) is “true”. 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to the 
data structure associated with msqid (see intro (2)). 

Msg qnum is decremented by 1 . 

Msg_lrpid is set equal to the process ID of the calling process. 
Msgrtime is set equal to the current time. 

SEE ALSO 

intro (2), msgctl(2), msgget(2), signal (2). 

DIAGNOSTICS 

If msgsnd or msgrcv return due to the receipt of a signal, a value of —1 is 
returned to the calling process and errno is set to EINTR. If they return due to 
removal of msqid from the system, a value of — 1 is returned and errno is set to 
EIDRM. 

Upon successful completion, the return value is as follows: 

Msgsnd returns a value of 0. 

Msgrcv returns a value equal to the number of bytes actually placed 
into mtext. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

nice — change priority of a process 

SYNOPSIS 

int nice (incr) 
int incr; 

DESCRIPTION 

Nice adds the value of incr to the nice value of the calling process. A process’s 
nice value is a positive number for which a more positive value results in lower 
CPU priority. 

A maximum nice value of 39 and a minimum nice value of 0 are imposed by 
the system. Requests for values above or below these limits result in the nice 
value being set to the corresponding limit. 

[EPERM] Nice will fail and not change the nice value if incr is negative 

or greater than 40 and the effective user ID of the calling pro- 
cess is not super-user. 

SEE ALSO 

exec (2). 

nice(l) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

Upon successful completion, nice returns the new nice value minus 20. Other- 
wise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

open — open for reading or writing 

SYNOPSIS 

#include <fcntl.h> 

int open (path, oflag [ , mode ] ) 

char *path; 

int oflag, mode; 

DESCRIPTION 

Path points to a path name naming a file. Open opens a file descriptor for the 
named file and sets the file status flags according to the value of oflag. Oflag 
values are constructed by or-ing flags from the following list (only one of the 
first three flags below may be used): 

0_RD0NLY Open for reading only. 

OWRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

0_NDELAY This flag may affect subsequent reads and writes. See read (2) 

and write (2). 

When opening a FIFO with O RDONLY or O WRONLY set: 

If ONDELAY is set: 

An open for reading-only will return without delay. 
An open for writing-only will return an error if no pro- 
cess currently has the file open for reading. 

If O NDELAY is clear: 

An open for reading-only will block until a process 
opens the file for writing. An open for writing-only 
will block until a process opens the file for reading. 

When opening a file associated with a communication line: 

If O NDELAY is set: 

The open will return without waiting for carrier. 

If O NDELAY is clear: 

The open will block until carrier is present. 

0_APPEND If set, the file pointer will be set to the end of the file prior to 
each write. 

0_SYNC When opening a regular file, this flag affects subsequent writes. 

If set, each write (2) will wait for both the file data and file 
status to be physically updated. 

0_CREAT If the file exists, this flag has no effect. Otherwise, the owner 
ID of the file is set to the effective user ID of the process, the 
group ID of the file is set to the effective group ID of the pro- 
cess, and the low-order 12 bits of the file mode are set to the 
value of mode modified as follows (see creati. 2)): 

All bits set in the file mode creation mask of the pro- 
cess are cleared. See umaskil). 

The “save text image after execution bit” of the mode 
is cleared. See chmod (2) . 

OJTRUNC If the file exists, its length is truncated to 0 and the mode and 
owner are unchanged. 
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OEXCL If OEXCL and OCREAT are set, open will fail if the file 

exists. 

The file pointer used to mark the current position within the file is set to the 
beginning of the file. 

The new file descriptor is set to remain open across exec system calls. See 
fcntl (2) . 


The named file is 

[ENOTDIR] 

[ENOENT] 

[EACCESl 

[EACCESl 

[EISDIRl 

[EROFSl 


opened unless one or more of the following are true: 

A component of the path prefix is not a directory. 

O CREAT is not set and the named file does not exist. 

A component of the path prefix denies search permission. 

Oflag permission is denied for the named file. 

The named file is a directory and oflag is write or read/write. 

The named file resides on a read-only file system and oflag is 
write or read/write. 


[EMFILEl 

[ENXIOl 

[ETXTBSY] 

[EFAULTl 

[EEXIST] 

[ENXIOl 


Twenty (20) file descriptors are currently open. 

The named file is a character special or block special file, and 
the device associated with this special file does not exist. 

The file is a pure procedure (shared text) file that is being 
executed and oflag is write or read/write. 

Path points outside the allocated address space of the process. 
O CREAT and O EXCL are set, and the named file exists. 

OJVDELAY is set, the named file is a FIFO, O WRONLY is 
set, and no process has the file open for reading. 


[EINTR] A signal was caught during the open system call. 

[ENFILEl The system file table is full. 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), lseek(2), read(2), umask(2), 
write (2). 


DIAGNOSTICS 

Upon successful completion, the file descriptor is returned. Otherwise, a value 
of —1 is returned and errno is set to indicate the error. 
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NAME 

pause — suspend process until signal 

SYNOPSIS 

pause 0 

DESCRIPTION 

Pause suspends the calling process until it receives a signal. The signal must 
be one that is not currently set to be ignored by the calling process. 

If the signal causes termination of the calling process, pause will not return. 

If the signal is caught by the calling process and control is returned from the 
signal-catching function (see signal (2)), the calling process resumes execution 
from the point of suspension; with a return value of —1 from pause and errno 
set to EINTR. 

SEE ALSO 

alarm (2), kill (2), signal (2), wait (2). 
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NAME 

pipe — create an interprocess channel 

SYNOPSIS 

int pipe (Hides) 
int fildesl2l; 

DESCRIPTION 

Pipe creates an I/O mechanism called a pipe and returns two file descriptors, 
fildesl 0] and fildes[\\. Fildes[ 0] is opened for reading and fildes [ 1 ] is opened 
for writing. 

Up to 5120 bytes of data are buffered by the pipe before the writing process is 
blocked. A read only file descriptor fildesl 0] accesses the data written to 
fildesl 1] on a first-in-first-out (FIFO) basis. 

[EMF5LE] Pipe will fail if 19 or more file descriptors are currently open. 

[ENFILE] The system file table is full. 

SEE ALSO 

read (2), write(2). 

sh(l) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

plock — lock process, text, or data in memory 
SYNOPSIS 

#include <sys/lock.h> 

int plock (op) 
int op; 


DESCRIPTION 

Plock allows the calling process to lock its text segment (text lock), its data 
segment (data lock), or both its text and data segments (process lock) into 
memory. Locked segments are immune to all routine swapping. Plock also 
allows these segments to be unlocked. The effective user ID of the calling pro- 
cess must be super-user to use this call. Op specifies the following: 

PROCLOCK - lock text and data segments into memory (process 
lock) 


TXTLOCK - 
DATLOCK - 
UNLOCK - 


lock text segment into memory (text lock) 
lock data segment into memory (data lock) 
remove locks 


Plock will fail and not perform the requested operation if one or more of the 
following are true: 


[EPERM] 

[EINVALl 

[EINVAL] 

[EINVALl 

[EINVAL] 


The effective user ID of the calling process is not super-user. 

Op is equal to PROCLOCK and a process lock, a text lock, or a 
data lock already exists on the calling process. 

Op is equal to TXTLOCK and a text lock, or a process lock 
already exists on the calling process. 

Op is equal to DATLOCK and a data lock, or a process lock 
already exists on the calling process. 

Op is equal to UNLOCK and no type of lock exists on the cal- 
ling process. 


SEE ALSO 

exec (2), exit (2), fork (2). 


DIAGNOSTICS 

Upon successful completion, a value of 0 is returned to the calling process. 
Otherwise, a value of — 1 is returned and errno is set to indicate the error. 
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NAME 

profil — execution time profile 
SYNOPSIS 

void profil (buff, bufsiz, offset, scale) 
char *buff; 

int bufsiz, offset, scale; 

DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by bufsiz. After 
this call, the user’s program counter (pc) is examined each clock tick (60th 
second); offset is subtracted from it, and the result multiplied by scale. If the 
resulting number corresponds to a word inside buff , that word is incremented. 

The scale is interpreted as an unsigned, fixed-point fraction with binary point at 
the left: 0177777 (octal) gives a 1-1 mapping of pc’s to words in buff ; 077777 
(octal) maps each pair of instruction words together. 02 (octal) maps all 
instructions onto the beginning of buff (producing a non-interrupting core 
clock) . 

Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by 
giving a bufsiz of 0. Profiling is turned off when an exec is executed, but 
remains on in child and parent both after a fork. Profiling will be turned off if 
an update in buff would cause a memory fault. 

SEE ALSO 

monitor(3C). 

prof(l) in the 3B2 Computer System Extended Software Generation Utilities. 

DIAGNOSTICS 

Not defined. 
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NAME 

ptrace — process trace 
SYNOPSIS 

int ptrace (request, pid, addr, data); 
int request, pid, addr, data; 

DESCRIPTION 

Ptrace provides a means by which a parent process may control the execution 
of a child process. Its primary use is for the implementation of breakpoint 
debugging; see sdb(\). The child process behaves normally until it encounters 
a signal (see signal (2) for the list), at which time it enters a stopped state and 
its parent is notified via wait (2). When the child is in the stopped state, its 
parent can examine and modify its “core image” using ptrace. Also, the parent 
can cause the child either to terminate or continue, with the possibility of 
ignoring the signal that caused it to stop. 

The request argument determines the precise action to be taken by ptrace and 
is one of the following: 

0 This request must be issued by the child process if it is to be 
traced by its parent. It turns on the child’s trace flag that stipu- 
lates that the child should be left in a stopped state upon receipt 
of a signal rather than the state specified by func; see signal (2) . 
The pid, addr, and data arguments are ignored, and a return 
value is not defined for this request. Peculiar results will ensue if 
the parent does not expect to trace the child. 

The remainder of the requests can only be used by the parent process. For 
each, pid is the process ID of the child. The child must be in a stopped state 
before these requests are made. 

1, 2 With these requests, the word at location addr in the address 
space of the child is returned to the parent process. If I and D 
space are separated, request 1 returns a word from I space, and 
request 2 returns a word from D space. If I and D space are not 
separated, either request 1 or request 2 may be used with equal 
results. The data argument is ignored. These two requests will 
fail if addr is not the start address of a word, in which case a 
value of —1 is returned to the parent process and the parent’s 
errno is set to EIO. 

3 With this request, the word at location addr in the child’s USER 
area in the system’s address space (see <sys/user.h>) is 
returned to the parent process. The data argument is ignored. 
This request will fail if addr is not the start address of a word or 
is outside the USER area, in which case a value of — 1 is returned 
to the parent process and the parent’s errno is set to EIO. 

4, 5 With these requests, the value given by the data argument is 
written into the address space of the child at location addr. If I 
and D space are separated, request 4 writes a word into I space, 
and request 5 writes a word into D space. If I and D space are 
not separated, either request 4 or request 5 may be used with 
equal results. Upon successful completion, the value written into 
the address space of the child is returned to the parent. These 
two requests will fail if addr is a location in a pure procedure 
space and another process is executing in that space, or addr is 
not the start address of a word. Upon failure a value of —1 is 
returned to the parent process and the parent’s errno is set to 
EIO. 
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6 With this request, a few entries in the child’s USER area can be 
written. Data gives the value that is to be written and ad dr is 
the location of the entry. The few entries that can be written 
are: 

the general registers 

the condition codes of the Processor Status Word. 

7 This request causes the child to resume execution. If the data 
argument is 0, all pending signals including the one that caused 
the child to stop are canceled before it resumes execution. If the 
data argument is a valid signal number, the child resumes execu- 
tion as if it had incurred that signal, and any other pending sig- 
nals are canceled. The addr argument must be equal to 1 for 
this request. Upon successful completion, the value of data is 
returned to the parent. This request will fail if data is not 0 or a 
valid signal number, in which case a value of —1 is returned to 
the parent process and the parent’s errno is set to EIO. 

8 This request causes the child to terminate with the same conse- 
quences as exit (2) . 

9 This request sets the trace bit in the Processor Status Word of 
the child and then executes the same steps as listed above for 
request 7. The trace bit causes an interrupt upon completion of 
one machine instruction. This effectively allows single stepping 
of the child. 

To forestall possible fraud, ptrace inhibits the set-user-id facility on subsequent 

exec (,2) calls. If a traced process calls exec, it will stop before executing the 

first instruction of the new image showing signal SIGTRAP. 

General Errors 

Ptrace will in general fail if one or more of the following are true: 

[EIO] Request is an illegal number. 

[ESRCH] Pid identifies a child that does not exist or has not executed a 

ptrace with request 0. 

SEE ALSO 

exec (2), signal (2), wait (2). 

sdb(l) in the 3B2 Computer System Extended Software Generation Utilities. 
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NAME 

read — read from file 
SYNOPSIS 

int read (tildes, buf, nbyte) 
int tildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe sys- 
tem call. 

Read attempts to read nbyte bytes from the file associated with fildes into the 
buffer pointed to by buf. 

On devices capable of seeking, the read starts at a position in the file given by 
the file pointer associated with fildes. Upon return from read, the file pointer 
is incremented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position. 
The value of a file pointer associated with such a file is undefined. 

Upon successful completion, read returns the number of bytes actually read 
and placed in the buffer; this number may be less than nbyte if the file is asso- 
ciated with a communication line (see ioctlti) and termioil)) , or if the 
number of bytes left in the file is less than nbyte bytes. A value of 0 is 
returned when an end-of-file has been reached. 

When attempting to read from an empty pipe (or FIFO): 

If ONDELAY is set, the read will return a 0. 

If O NDELAY is clear, the read will block until data is written to the 
file or the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no data currently 
available: 

If O NDELAY is set, the read will return a 0. 

If O NDELAY is clear, the read will block until data becomes avail- 
able. 

Read will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EFAULT] Buf points outside the allocated address space. 

[EINTR] A signal was caught during the read system call. 

SEE ALSO 

creat (2), dup (2), fcntl (2), ioctl(2), open (2), pipe (2). 

termio(7) in the 3B2 Computer System Administration Utilities Guide. 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating the 
number of bytes actually read. Otherwise, a —1 is returned and errno is set to 
indicate the error. 
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NAME 

semctl — semaphore control operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semctl (semid, semnum, cmd, arg) 
int semid, cmd; 
int semnum; 
union semun { 
int val; 

struct semid_ds *buf; 
ushort *array; 

} arg; 

DESCRIPTION 

Semctl provides a variety of semaphore control operations as specified by cmd. 

The following cmds are executed with respect to the semaphore specified by 
semid and semnum: 

GETVAL Return the value of semval (see intro (2)). (READ) 

SETVAL Set the value of semval to arg.val. (ALTER) When this 

cmd is successfully executed, the semadj value 
corresponding to the specified semaphore in all processes 
is cleared. 

GETPID Return the value of sempid. (READ) 

GETNCNT Return the value of semncnt. (READ) 

GETZCNT Return the value of semzcnt. (READ) 

The following cmd s return and set, respectively, every semval in the set of 
semaphores. 

GETALL Place semvals into array pointed to by arg.array. 

(READ) 

SETALL Set semvals according to the array pointed to by 

arg.array. (ALTER) When this cmd is successfully exe- 
cuted the semadj values corresponding to each specified 
semaphore in all processes are cleared. 

The following cmd s are also available: 

IPC STAT Place the current value of each member of the data 
structure associated with semid into the structure pointed 
to by arg.buf. The contents of this structure are defined 
in intro (.2). (READ) 

IPC_SET Set the value of the following members of the data struc- 
ture associated with semid to the corresponding value 
found in the structure pointed to by arg.buf : 

sem_perm.uid 

sem_perm.gid 

sem_perm.mode /• only low 9 bits »/ 

This cmd can only be executed by a process that has an 
effective user ID equal to either that of super-user or to 
the value of sem_perm.uid in the data structure associ- 
ated with semid. 
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IPCJRMID Remove the semaphore identifier specified by semid from 
the system and destroy the set of semaphores and data 
structure associated with it. This cmd can only be exe- 
cuted by a process that has an effective user ID equal to 
either that of super-user or to the value of sem_perm.uid 
in the data structure associated with semid. 

Semctl will fail if one or more of the following are true: 

[EINVAL] Semid is not a valid semaphore identifier. 

[EINVALl Semnum is less than zero or greater than semjisems. 

[EINVAL] Cmd is not a valid command. 

[EACCESl Operation permission is denied to the calling process 

(see intro (2)). 

[ERANGEl Cmd is SETVAL or SETALL and the value to which 
semval is to be set is greater than the system imposed 
maximum. 

[EPERM] Cmd is equal to IPC_RMID or IPC_SET and the 

effective user ID of the calling process is not equal to 
that of super-user and it is not equal to the value of 
sem_perm.uid in the data structure associated with 
semid. 

[EFAULTl Arg.buf points to an illegal address. 

SEE ALSO 

intro (2), semget(2), semop(2). 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

GETVAL The value of semval. 

GETPID The value of sempid. 

GETNCNT The value of semncnt. 

GETZCNT The value of semzcnt. 

All others A value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

semget — get set of semaphores 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semget (key, nsems, semflg) 

keyt key; 

int nsems, semflg; 

DESCRIPTION 

Semget returns the semaphore identifier associated with key. 

A semaphore identifier and associated data structure and set containing nsems 
semaphores (see intro (2)) are created for key if one of the following are true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a semaphore identifier associated with it, 
and ( semflg & IPC_CREAT) is “true”. 

Upon creation, the data structure associated with the new semaphore identifier 
is initialized as follows: 

Sem_perm.cuid, semjerm.uid, sem jerm.cgid, and sem_perm.gid are set 
equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of sem_perm.mode are set equal to the low-order 9 
bits of semflg. 

Sem nsems is set equal to the value of nsems. 

Sem otime is set equal to 0 and sem etime is set equal to the current 
time. 


Semget will fail if one or more of the following are true: 


[EINVAL] 

[EACCESl 

[EINVAL] 

[ENOENT] 

[ENOSPC] 

[ENOSPC1 

[EEXIST] 


Nsems is either less than or equal to zero or greater than the 
system-imposed limit. 

A semaphore identifier exists for key, but operation permis- 
sion (see intro (2)) as specified by the low-order 9 bits of 
semflg would not be granted. 

A semaphore identifier exists for key, but the number of 
semaphores in the set associated with it is less than nsems and 
nsems is not equal to zero. 

A semaphore identifier does not exist for key and ( semflg & 
IPC_CREAT) is “false”. 

A semaphore identifier is to be created but the system- 
imposed limit on the maximum number of allowed semaphore 
identifiers system wide would be exceeded. 

A semaphore identifier is to be created but the system- 
imposed limit on the maximum number of allowed semaphores 
system wide would be exceeded. 

A semaphore identifier exists for key but ( ( semflg & 
IPC_CREAT) and ( semflg & IPC_EXCL) ) is “true”. 
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SEE ALSO 

intro(2), semctl(2), semop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a semaphore 
identifier, is returned. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 
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NAME 

semop — semaphore operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semop (semid, sops, nsops) 
int semid; 

struct sembuf **sops; 
int nsops; 

DESCRIPTION 

Semop is used to automatically perform an array of semaphore operations on 
the set of semaphores associated with the semaphore identifier specified by 
semid. Sops is a pointer to the array of semaphore-operation structures. 
Nsops is the number of such structures in the array. The contents of each 
structure includes the following members: 

short sem_num; /* semaphore number */ 

short sem op; /* semaphore operation »/ 

short semflg; /* operation flags »/ 

Each semaphore operation specified by sem op is performed on the correspond- 
ing semaphore specified by semid and semjium. 

Sem_op specifies one of three semaphore operations as follows: 

If sem op is a negative integer, one of the following will occur: 
(ALTER) 

If semval (see intro (2)) is greater than or equal to the abso- 
lute value of sem op , the absolute value of sem_op is sub- 
tracted from semval. Also, if (.sem Jig & SEM_UNDO) is 
“true”, the absolute value of sem_op is added to the calling 
process’s semadj value (see exit (,2)) for the specified sema- 
phore. 

If semval is less than the absolute value of sem_op and 
( sem Jig & IPC_NOWAIT) is “true”, semop will return 
immediately. 

If semval is less than the absolute value of sem_op and 
( sem Jig & IPC_NOWAIT) is “false”, semop will increment 
the semncnt associated with the specified semaphore and 
suspend execution of the calling process until one of the fol- 
lowing conditions occur. 

Semval becomes greater than or equal to the absolute value 
of sem op. When this occurs, the value of semncnt associ- 
ated with the specified semaphore is decremented, the abso- 
lute value of sem op is subtracted from semval and, if 
( sem Jig & SEM_UNDO) is “true”, the absolute value of 
sem_op is added to the calling process’s semadj value for the 
specified semaphore. 

The semid for which the calling process is awaiting action is 
removed from the system (see semctK 2)). When this occurs, 
errno is set equal to EIDRM, and a value of — 1 is returned. 
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The calling process receives a signal that is to be caught. 
When this occurs, the value of semncnt associated with the 
specified semaphore is decremented, and the calling process 
resumes execution in the manner prescribed in signal (2) . 

If semop is a positive integer, the value of sem_op is added to semval 
and, if (sem Jig & SEMUNDO) is “true”, the value of sem op is sub- 
tracted from the calling process’s semadj value for the specified sema- 
phore. (ALTER) 

If sem op is zero, one of the following will occur: (READ) 


If semval is zero, semop will return immediately. 

If semval is not equal to zero and ( semjlg & IPC_NOWAIT) 
is “true”, semop will return immediately. 

If semval is not equal to zero and ( sem Jig & IPC_NOWAIT) 
is “false”, semop will increment the semzcnt associated with 
the specified semaphore and suspend execution of the calling 
process until one of the following occurs: 

Semval becomes zero, at which time the value of semzcnt 
associated with the specified semaphore is decremented. 

The semid for which the calling process is awaiting action is 
removed from the system. When this occurs, errno is set 
equal to EIDRM, and a value of —1 is returned. 

The calling process receives a signal that is to be caught. 
When this occurs, the value of semzcnt associated with the 
specified semaphore is decremented, and the calling process 
resumes execution in the manner prescribed in signal (2) . 

Semop will fail if one or more of the following are true for any of the sema- 
phore operations specified by sops: 


[EINVAL] 

[EFBIG1 

[E2BIG] 

[EACCES] 


Semid is not a valid semaphore identifier. 

Semjium is less than zero or greater than or equal to the 
number of semaphores in the set associated with semid. 

Nsops is greater than the system-imposed maximum. 

Operation permission is denied to the calling process (see 
intro (2)). 


[EAGAIN] 

[ENOSPC] 

[EINVAL] 

[ERANGE] 

[ERANGE] 

[EFAULT] 


The operation would result in suspension of the calling process 
but (sem Jig & IPC_NOWAIT) is “true”. 

The limit on the number of individual processes requesting an 
SEM UNDO would be exceeded. 

The number of individual semaphores for which the calling 
process requests a SEMJJNDO would exceed the limit. 

An operation would cause a semval to overflow the system- 
imposed limit. 

An operation would cause a semadj value to overflow the 
system-imposed limit. 

Sops points to an illegal address. 


Upon successful completion, the value of sempid for each semaphore specified 
in the array pointed to by sops is set equal to the process ID of the calling pro- 
cess. 
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SEE ALSO 

exec(2), exit(2), fork(2), intro(2), semctl(2), semget(2). 

DIAGNOSTICS 

If semop returns due to the receipt of a signal, a value of —1 is returned to the 
calling process and errno is set to EINTR. If it returns due to the removal of a 
semid from the system, a value of —1 is returned and errno is set to EIDRM. 

Upon successful completion, the value of semval at the time of the call for the 
last operation in the array pointed to by sops is returned. Otherwise, a value of 
—1 is returned and errno is set to indicate the error. 
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NAME 

setpgrp — set process group ID 

SYNOPSIS 

int setpgrp 0 

DESCRIPTION 

Setpgrp sets the process group ID of the calling process to the process ID of the 
calling process and returns the new process group ID. 

SEE ALSO 

exec (2), fork (2), getpid(2), intro (2), kill (2), signal (2). 

DIAGNOSTICS 

Setpgrp returns the value of the new process group ID. 
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NAME 

setuid, setgid — set user and group IDs 

SYNOPSIS 

int setuid (uid) 
int uid; 

int setgid (gid) 
int gid; 

DESCRIPTION 

Setuid ( setgid ) is used to set the real user (group) ID and effective user 
(group) ID of the calling process. 

If the effective user ID of the calling process is super-user, the real user (group) 
ID and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but its real user 
(group) ID is equal to uid (gid), the effective user (group) ID is set to uid 
(gid). 

If the effective user ID of the calling process is not super-user, but the saved 
set-user (group) ID from exec(2) is equal to uid (gid), the effective user 
(group) ID is set to uid (gid). 

Setuid (setgid) will fail if the real user (group) ID of the calling process is not 
equal to uid (gid) and its effective user ID is not super-user. [EPERM] 

The uid is out of range. [EINVAL] 

SEE ALSO 

getuid(2), intro (2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

shmctl - shared memory control operations 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/page.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmctl (shmid, cmd, buf) 
int shmid, cmd; 
struct shmid jls *buf; 


DESCRIPTION 

Shmctl provides a variety of shared memory control operations as specified by 
cmd. The following cmds are available: 

IPCJSTAT Place the current value of each member of the data 
structure associated with shmid into the structure 
pointed to by buf. The contents of this structure are 
defined in [EINVALl intro (2). (READ) 

IPC_SET Set the value of the following members of the data struc- 
ture associated with shmid to the corresponding value 
found in the structure pointed to by buf: 
shm_perm.uid 
shm_perm.gid 

shm_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process that has an 
effective user ID equal to either that of super user or to 
the value of shm_perm[i].uid in the data structure associ- 
ated with shmid. 


IPCJRMID Remove the shared memory identifier specified by shmid 
from the system and destroy the shared memory segment 
and data structure associated with it. This cmd can only 
be executed by a process that has an effective user ID 
equal to either that of super user or to the value of 
shm_perm[i].uid in the data structure associated with 
shmid. 


SHM_LOCK Lock the shared memory segment specified by shmid in 
memory. This cmd can only be executed by a process 
that has an effective usr ID equal to super user. 


SHMJJNLOCK 

Unlock the shared memory segment specified by shmid. 
This cmd can only be executed by a process that has an 
effective usr ID equal to super user. 

Shmctl will fail if one or more of the following are true: 

[EINVALl 

Shmid is not a valid shared memory identifier. 

[EINVALl 

Cmd is not a valid command. 


[EACCESS] 

Cmd is equal to IPC_STAT and (READ) operation permission is 
denied to the calling process [see intro (. 2)]. 


[EPERMl 

Cmd is equal to IPC RMID or IPCSET and the effective user 
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ID of the calling process is not equal to that of super user and 
it is not equal to the value of shm_perm.uid in the data struc- 
ture associated with shmid. 

[EPERMl 

Cmd is equal to SHM_LOCK or SHMJJNLOCK and the 
effective user ID of the calling process is not equal to that of 
super user. 

[EINVAL] 

Cmd is equal to SHMJUNLOCK and the shared-memory seg- 
ment specified by shmid is not locked in memory. 

[EFAULT] 

Buf points to an illegal address. 

SEE ALSO 

shmget(2), shmop(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

shmget — get shared memory segment 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/page.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmget (key, size, shmflg) 

key_t key; 

int size, shmflg; 

DESCRIPTION 

Shmget returns the shared memory identifier associated with key. 

A shared memory identifier and associated data structure and shared memory 
segment of size size bytes (see intro (.2)) are created for key if one of the fol- 
lowing are true: 

Key is equal to IPCPRIVATE. 

Key does not already have a shared memory identifier associated with 
it, and ( shmflg & IPC_CREAT) is “true”. 

Upon creation, the data structure associated with the new shared memory 
identifier is initialized as follows: 


Shm_perm.cmd, shm_perm.uid, shm_perm.cgid, and shm_perm.gid are 

set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of shm jerm.mode are set equal to the low-order 9 
bits of shmflg. Shm_segsz is set equal to the value of size. 


Shm lpid, shm nattch, shm atime, and shm dtime are set equal to 0. 
Shm_ctime is set equal to the current time. 

Shmget will fail if one or more of the following are true: 


[EINVAL] 

[EACCES] 

[EINVAL] 

[ENOENT] 

[ENOSPC] 

[ENOMEM] 

[EEXIST] 


Size is less than the system-imposed minimum or greater than 
the system-imposed maximum. 

A shared memory identifier exists for key but operation per- 
mission (see intro (2)) as specified by the low-order 9 bits of 
shmflg would not be granted. 

A shared memory identifier exists for key but the size of the 
segment associated with it is less than size and size is not 
equal to zero. 

A shared memory identifier does not exist for key and ( shmflg 
& IPC_CREAT) is “false”. 

A shared memory identifier is to be created but the system- 
imposed limit on the maximum number of allowed shared 
memory identifiers system wide would be exceeded. 

A shared memory identifier and associated shared rnemory 
segment are to be created but the amount of available 
memory is not sufficient to fill the request. 

A shared memory identifier exists for key but ( ( shmflg & 
IPC_CREAT) and ( shmflg & IPC_EXCL) ) is “true”. 
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SEE ALSO 

intro (2), shmctl(2), shmop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a shared memory 
identifier is returned. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 
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NAME 

shmop — shared memory operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/page.h> 

#include <sys/ipc.h> 

#inciude <sys/shm.h> 

char 'shmat (shmid, shmaddr, shmflg) 
int shmid; 
char *shmaddr 
int shmflg; 

int shmdt (shmaddr) 
char 'shmaddr 


DESCRIPTION 

Shmat attaches the shared memory segment associated with the shared 
memory identifier specified by shmid to the data segment of the calling process. 
The segment is attached at the address specified by one of the following cri- 
teria: 


If shmaddr is equal to zero, the segment is attached at the first avail- 
able address as selected by the system. 

If shmaddr is not equal to zero and ( shmflg & SHM_RND) is “true”, 
the segment is attached at the address given by ( shmaddr - (.shmaddr 
modulus SHMLBA)). 


If shmaddr is not equal to zero and (shmflg & SHMRND) is “false”, 
the segment is attached at the address given by shmaddr. 

The segment is attached for reading if (shmflg & SHMRDONLY) is “true” 
(READ), otherwise it is attached for reading and writing (READ/WRITE). 

Shmat will fail and not attach the shared memory segment if one or more of 
the following are true: 

[EINVAL] Shmid is not a valid shared memory identifier. 

[EACCES] Operation permission is denied to the calling process (see 

intro ( 2)). 


[ENOMEMl 

[EINVAL] 

[EINVAL] 

[EMFILE] 

[EINVAL] 


The available data space is not large enough to accommodate 
the shared memory segment. 

Shmaddr is not equal to zero, and the value of (shmaddr - 
(shmaddr modulus SHMLBA)) is an illegal address. 

Shmaddr is not equal to zero, (shmflg & SHM RND) is 
“false”, and the value of shmaddr is an illegal address. 

The number of shared memory segments attached to the cal- 
ling process would exceed the system-imposed limit. 

Shmdt detaches from the calling process’s data segment the 
shared memory segment located at the address specified by 
shmaddr. 


[EINVAL] Shmdt will fail and not detach the shared memory segment if 

shmaddr is not the data segment start address of a shared 
memory segment. 
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SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2). 

DIAGNOSTICS 

Upon successful completion, the return value is as follows: 

Shmat returns the data segment start address of the attached shared 
memory segment. 

Shmdt returns a value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

signal — specify what to do upon receipt of a signal 

SYNOPSIS 

#include <signal.h> 

int (‘signal (sig, func))() 
int sig; 

void (*func)(); 

DESCRIPTION 

Signal allows the calling process to choose one of three ways in which it is pos- 
sible to handle the receipt of a specific signal. Sig specifies the signal and func 
specifies the choice. 

Sig can be assigned any one of the following except SIGKILL: 


SIGHUP 

01 

hangup 

SIGINT 

02 

interrupt 

SIGQUIT 

03* 

quit 

SIGILL 

04* 

illegal instruction (not reset when caught) 

SIGTRAP 

05* 

trace trap (not reset when caught) 

SIGIOT 

06* 

IOT instruction 

SIGEMT 

07* 

EMT instruction 

SIGFPE 

08* 

floating point exception 

SIGKILL 

09 

kill (cannot be caught or ignored) 

SIGBUS 

10* 

bus error 

SIGSEGV 

11* 

segmentation violation 

SIGSYS 

12* 

bad argument to system call 

SIGPIPE 

13 

write on a pipe with no one to read it 

SIGALRM 

14 

alarm clock 

SIGTERM 

15 

software termination signal 

SIGUSR1 

16 

user-defined signal 1 

SIGUSR2 

17 

user-defined signal 2 

SIGCLD 

18 

death of a child 
(see WARNING below) 

SIGPWR 

19 

power fail 

(see WARNING below) 


See below for the significance of the asterisk (•) in the above list. 

Func is assigned one of three values: SIG_DFL, SIG_IGN, or a function address. 

The actions prescribed by these values are as follows: 

SIG_DFL — terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be ter- 
minated with all of the consequences outlined in exit (2). In addi- 
tion a “core image” will be made in the current working directory 
of the receiving process if sig is one for which an asterisk appears in 
the above list and the following conditions are met: 

The effective user ID and the real user ID of the receiving 
process are equal. 

An ordinary file named core exists and is writable or can 
be created. If the file must be created, it will have the fol- 
lowing properties: 

a mode of 0666 modified by the file creation 
mask (see umaskiZ)) 

a file owner ID that is the same as the effective 
user ID of the receiving process. 
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a file group ID that is the same as the effective 
group ID of the receiving process 

SIGIGN — ignore signal 

The signal sig is to be ignored. 

Note: the signal SIGKILL cannot be ignored. 
function address — catch signal 

Upon receipt of the signal sig, the receiving process is to execute the 
signal-catching function pointed to by func. The signal number sig 
will be passed as the only argument to the signal-catching function. 
Additional arguments are passed to the signal-catching function for 
hardware-generated signals. Before entering the signal-catching func- 
tion, the value of func for the caught signal will be set to SIGDFL 
unless the signal is SIGILL, SIGTRAP, or SIGPWR. 

Upon return from the signal-catching function, the receiving process 
will resume execution at the point it was interrupted. 

When a signal that is to be caught occurs during a read, a write, an 
open, or an ioctl system call on a slow device (like a terminal; but not 
a file), during a pause system call, or during a wait system call that 
does not return immediately due to the existence of a previously 
stopped or zombie process, the signal catching function will be exe- 
cuted and then the interrupted system call may return a —1 to the 
calling process with errno set to EINTR. 

Note: The signal SIGKILL cannot be caught. 

A call to signal cancels a pending signal sig except for a pending SIGKILL sig- 
nal. 

Signal will fail if sig is an illegal signal number, including SIGKILL. [EINVAL] 
SEE ALSO 

kill(2), pause(2), ptrace(2), wait(2), setjmp(3C). 

kill ( 1 ) in the 3B2 Computer System User Reference Manual. 

WARNING 

Two other signals that behave differently than the signals described above exist 
in this release of the system; they are: 

SIGCLD 18 death of a child (reset when caught) 

SIGPWR 19 power fail (not reset when caught) 

There is no guarantee that, in future releases of the UNIX system, these signals 
will continue to behave as described below; they are included only for compati- 
bility with other versions of the UNIX system. Their use in new programs is 
strongly discouraged. 

For these signals, func is assigned one of three values: SIG_DFL, SIG IGN, or a 
function address. The actions prescribed by these values of are as follows: 

SIG DFL - ignore signal 

The signal is to be ignored. 

SIG_IGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the calling 
process’s child processes will not create zombie processes when they 
terminate; see exit (.2). 

function address - catch signal 

If the signal is SIGPWR, the action to be taken is the same as that 
described above for func equal to function address. The same is 
true if the signal is SIGCLD except, that while the process is 
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executing the signal-catching function, any received SIGCLD signals 
will be queued and the signal-catching function will be continually 
reentered until the queue is empty. 

The SIGCLD affects two other system calls (wait {2), and exit (2)) in the fol- 
lowing ways: 

wait If the func value of SIGCLD is set to SIGJGN and a wait is exe- 
cuted, the wait will block until all of the calling process’s child 
processes terminate; it will then return a value of —1 with errno set 
to ECHILD. 

exit If in the exiting process’s parent process the func value of SIGCLD is 
set to SIGIGN, the exiting process will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the pipeline 
the parent of the proceeding processes. A process that may be piped into in 
this manner (and thus become the parent of other processes) should take 
care not to set SIGCLD to be caught. 

DIAGNOSTICS 

Upon successful completion, signal returns the previous value of func for the 
specified signal sig. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 
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NAME 

stat, fstat — get file status 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

int stat (path, buf) 
char *path; 
struct stat *buf; 

int fstat (fildes, buf) 
int fildes; 
struct stat »buf; 

DESCRIPTION 

Path points to a path name naming a file. Read, write, or execute permission 
of the named file is not required, but all directories listed in the path name 
leading to the file must be searchable. Stat obtains information about the 
named file. 

Similarly, fstat obtains information about an open file known by the file 
descriptor fildes, obtained from a successful open, creat, dup, fcntl, or pipe 
system call. 

Buf is a pointer to a stat structure into which information is placed concerning 
the file. 

The contents of the structure pointed to by buf include the following members: 


ushort 

stmode; 

/* File mode; see mknodil) */ 

ino_t 

st_ino; 

/* Inode number */ 

dev_t 

stdev; 

/* ID of device containing */ 

/* a directory entry for this file */ 

dev_t 

st_rdev; 

/» ID of device »/ 

/* This entry is defined only for */ 

/» character special or block special files »/ 

short 

st_nlink; 

/* Number of links */ 

ushort 

st_uid; 

/* User ID of the file’s owner */ 

ushort 

st jgid; 

/* Group ID of the file’s group */ 

oflfj 

st_size; 

/* File size in bytes */ 

time_t 

st_atime; 

/* Time of last access */ 

time_t 

stmtime; 

/* Time of last data modification */ 

time_t 

stctime; 

/* Time of last file status change */ 

/* Times measured in seconds since »/ 

/* 00:00:00 GMT, Jan. 1, 1970 »/ 


st atime Time when file data was last accessed. Changed by the following 
system calls: creat (2), mknodti), pipe (2), utime(2), and read (2). 

st_mtime Time when data was last modified. Changed by the following sys- 
tem calls: creat (2), mknodil), pipe (2), utimei 2), and write (2). 

stctime Time when file status was last changed. Changed by the following 
system calls: chmod(2), chownil), creat (2), link (2), mknod{2), 
pipe (2), unlink(2), utimeil), and write (2). 

Stat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCESl Search permission is denied for a component of the path 

prefix. 


10/84 


- 1 - 


10/84 



STAT(2) 


STAT (2) 


[EFAULT] Buf or path points to an invalid address. 

Fstat will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 

SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), time(2), 
unlink(2), utime(2), write(2). 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

stime — set time 

SYNOPSIS 

int stime (tp) 
long »tp; 

DESCRIPTION 

Stime sets the system’s idea of the time and date. Tp points to the value of 
time as measured in seconds from 00:00:00 GMT January 1, 1970. 

[EPERM] Stime will fail if the effective user ID of the calling process is 

not super-user. 

SEE ALSO 

time (2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

sync — update super block 

SYNOPSIS 

void sync ( ) 

DESCRIPTION 

Sync causes all information in memory that should be on disk to be written out. 
This includes modified super blocks, modified i-nodes, and delayed block I/O. 

It should be used by programs which examine a file system, for example fsck, 
df, etc. It is mandatory before a boot. 

The writing, although scheduled, is not necessarily complete upon return from 
sync. 
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NAME 

sys3b — machine specific function 
SYNOPSIS 

#include <sys/sys3b.h> 

int sys3b (cmd, argl, arg2, arg3) 
int cmd, argl, arg2, arg3; 

DESCRIPTION 

Sys3b implements machine specific functions. The cmd argument determines 
the function performed. The number of arguments expected is dependent on 
the function. 

Command S3BSYM 

When cmd is S3BSYM, the symbol table created during a self-config boot pro- 
cess may be accessed. The symbols defined within the driver routines loaded 
and those created from the /etc/master file variable specifications are available 
via this command. Two arguments are expected; the first must be a pointer to 
a buffer into which the symbol table is copied, and the second must be an 
integer containing the total size of the buffer. The format of the symbol table 
is: 


int 

size; 

/* 

symbol size in bytes */ 

int 

nsyms; 

/* 

total number of symbols */ 



/* 

for each symbol ... */ 

char 

named; 

/* 

name of symbol, padded with */ 



/* 

’ ’ to next sizeof(long) */ 



/* 

boundary */ 

long 

value; 

/* 

value of symbol */ 


Typically, the symbol table would be retrieved with two calls to sys3b. First, 
the size of the symbol table is obtained by calling sys3b with a buffer of one 
integer. This integer is then used to obtain a buffer large enough to contain the 
entire symbol table. The second invocation of sys3b with this newly obtained 
buffer retrieves the entire symbol table. 

#include <sys/sys3b.h> 


int size; /* size of buffer needed */ 

struct s3bsym *buffer; /* buffer pointer */ 


sys3b( S3BSYM, &size, sizeof(size) ); 
buffer = (struct s3bsym *) mallocf size ); 
sys3b( S3BSYM, buffer, size ); 

Command S3BCONF 

When cmd is S3BCONF, the configuration table created during a self-config 
boot process may be accessed. This table contains the names and locations of 
the devices supported by the currently running UNIX system, the names of all 
software modules included in the system, and the names of all devices in the 
EDT that were ignored. Two arguments are expected; the first must be a 
pointer to a buffer into which the configuration table is copied, and the second 
must be an integer containing the total size of the buffer. The format of the 
configuration table is: 
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int 

ndev; 

/* 

total number of entries */ 



/* 

for each entry ... */ 

long 

timestamp; 

/* 

f_timdat from file header */ 

char 

name[14l; 

/* 

name of device/module */ 

char 

flag; 

/* 

configuration information */ 



/* 

0x80: device ignored */ 



/* 

0x40: named is a driver */ 



/* 

0x20: named is a software module */ 

char 

board; 

/* 

local bus address of device */ 


Typically, the configuration table would be retrieved with two calls to sys3b. 
First, the number of entries is obtained by calling sys3b with a buffer of one 
integer. This integer is then used to calculate and obtain a buffer large enough 
to contain the entire configuration table. The second invocation of sys3b with 
this newly obtained buffer retrieves the configuration table. 

#include <sys/sys3b.h> 


int count; /* total number of devices */ 

int size; /* size of buffer needed */ 

struct s3bconf * buffer; /* buffer pointer */ 


sys3b( S3BCONF, & count, sizeof(count) ); 
size = sizeof(int); 

size += count * sizeof (struct s3bc); 
buffer = (struct s3bconf *) malloc( size ); 
sys3b( S3BCONF, buffer, size ); 

Command S3BBOOT 

When cmd is S3BBOOT, the timestamp and boot program path name used for 
a self-config boot process may be accessed. The path name of the a.out format 
file which was booted, and the timestamp from the file header (see a.out ( 4)) 
are saved. One argument is expected; a pointer to a buffer into which the 
information is copied. The format of this information is: 

long timestamp; /* f timdat from file header */ 
char pathllOO]; /* path name */ 

This information would be retrieved with a single call to sys3b. 

#include <sys/sys3b.h> 

struct s3bboot buffer; /* buffer */ 

sys3b( S3BBOOT, & buffer ); 

Command S3BAUTO 

When cmd is S3BAUTO, no arguments are expected. This function returns a 
boolean value in answer to the question "was the last boot an auto-config boot 
or was a fully configured file booted?". The value returned is zero if a fully 
configured file (such as /unix) was booted. The integer value 1 is returned if 
the preceeding boot was an auto-config boot. 

SEE ALSO 

sync(2), a.out(4). 


10/84 


- 2 - 


10/84 



TIME (2) 


TIME (2) 


NAME 

time — get time 
SYNOPSIS 

long time ((long *) 0) 

long time (tloc) 
long «tloc; 

DESCRIPTION 

Time returns the value of time in seconds since 00:00:00 GMT, January 1, 
1970. 

If tloc (taken as an integer) is non-zero, the return value is also stored in the 
location to which tloc points. 

[EFAULT] Time will fail if tloc points to an illegal address. 

SEE ALSO 

stime(2). 

DIAGNOSTICS 

Upon successful completion, time returns the value of time. Otherwise, a value 
of —1 is returned and errno is set to indicate the error. 
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NAME 

times — get process and child process times 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/times.h> 

long times (buffer) 
struct tms ‘buffer; 

DESCRIPTION 

Times fills the structure pointed to by buffer with time-accounting information. 
The following are the contents of this structure: 

struct tms { 

time_t tms_utime; 
timet tmsstime; 
timet tms_cutime; 
timet tmscstime; 

}; 

This information comes from the calling process and each of its terminated 
child processes for which it has executed a wait. All times are in 60ths of a 
second on DEC processors, lOOths of a second on AT&T processors. 

Tmsutime is the CPU time used while executing instructions in the user space 
of the calling process. 

Tms stime is the CPU time used by the system on behalf of the calling process. 
Tmscutime is the sum of the tmsutimes and tmscutime s of the child 
processes. 

Tms cstime is the sum of the tms_stime s and tms cstime s of the child 
processes. 

[EFAULT] Times will fail if buffer points to an illegal address. 

SEE ALSO 

exec(2), fork(2), time(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, times returns the elapsed real time, in 60ths 
(lOOths) of a second, since an arbitrary point in the past (e.g., system start-up 
time). This point does not change from one invocation of times to another. If 
times fails, a —1 is returned and errno is set to indicate the error. 
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NAME 

uadmin — administrative control 
SYNOPSIS 

#include <sys/uadmin.h> 

int uadmin (cmd, fen, mdep) 
int cmd, fen, mdep; 

DESCRIPTION 

Uadmin provides control for basic administrative functions. This system call is 
tightly coupled to the system administrative procedures and is not intended for 
general use. The argument mdep is provided for machine-dependent use and is 
not defined here. 

The commands available as specified by cmd are: 

ASHUTDOWN The system is shutdown. All user processes are killed, the 
buffer cache is flushed, and the root file system is unmounted. 
The action to be taken after the system is shutdown is 
specified by fen. The functions are generic, on specific 
machines the hardware capabilities will vary. 

ADHALT Halt the processor and turn off power. 

AD BOOT Reboot the system, use /unix. 

AD IBOOT Interactive reboot, prompt for system name. 

AREBOOT The system stops immediately without any further processing. 

The aetton io be taken next is specified by fen as above. 

AREMOUNT The root file system is mounted again after having been fixed. 
This should only be used during the startup process. 

Uadmin will fail if any of the following are true: 

[EPERM] The effective user ID is not super-user. 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

A SHUTDOWN Never returns. 

A REBOOT Never returns. 

AREMOUNT 0 

Otherwise, a value of -1 is returned and errno is set to indicate the error, 
mount (2). 
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NAME 

ulimit — get and set user limits 

SYNOPSIS 

long ulimit (cmd, newlimit) 
int cmd; 
long newlimit; 

DESCRIPTION 

This function provides for control over process limits. The cmd values available 
are: 

1 Get the file size limit of the process. The limit is in units of 512-byte 
blocks and is inherited by child processes. Files of any size can be read. 

2 Set the file size limit of the process to the value of newlimit. Any process 
may decrease this limit, but only a process with an effective user ID of 
super-user may increase the limit. Ulimit will fail and the limit will be 
unchanged if a process with an effective user ID other than super-user 
attempts to increase its file size limit. [EPERM] 

3 Get the maximum possible break value. Seebrk(2). 

SEE ALSO 

brk(2), write (2). 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 
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NAME 

umask — set and get file creation mask 

SYNOPSIS 

int umask (cmask) 
int cmask; 

DESCRIPTION 

Umask sets the process’s file mode creation mask to cmask and returns the pre- 
vious value of the mask. Only the low-order 9 bits of cmask and the file mode 
creation mask are used. 

SEE ALSO 

chmod(2), creat(2), mknod(2), open (2). 

mkdir(l), sh(l) in the 3B2 Computer System User Reference Manual. 
DIAGNOSTICS 

The previous value of the file mode creation mask is returned. 
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NAME 

umount — unmount a file system 


SYNOPSIS 

int umount (spec) 
char »spec; 


DESCRIPTION 

Umount requests that a previously mounted file system contained on the block 
special device identified by spec be unmounted. Spec is a pointer to a path 
name. After unmounting the file system, the directory upon which the file sys- 
tem was mounted reverts to its ordinary interpretation. 

Umount may be invoked only by the super-user. 

Umount will fail if one or more of the following are true: 


[EPERM] 

[ENXIOl 

[ENOTBLK] 

[EINVAL] 

[EBUSY] 

[EFAULT] 

SEE ALSO 

mount (2). 


The process’s effective user ID is not super-user. 
Spec does not exist. 

Spec is not a block special device. 

Spec is not mounted. 

A file on spec is busy. 

Spec points to an illegal address. 


DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

uname — get name of current UNIX system 
SYNOPSIS 

#include <sys/utsname.h> 

int uname (name) 
struct utsname *name; 

DESCRIPTION 

Uname stores information identifying the current UNIX system in the structure 
pointed to by name. 

Uname uses the structure defined in <sys/utsname.h> whose members are: 

char sysname[9]; 
char nodename[9]; 
char release[9l; 
char version[9]; 
char machine[9]; 

Uname returns a null-terminated character string naming the current UNIX 
system in the character array sysname. Similarly, nodename contains the 
name that the system is known by on a communications network. Release and 
version further identify the operating system. Machine contains a standard 
name that identifies the hardware that the UNIX system is running on. 

[EFAULT] Uname will fail if name points to an invalid address. 

SEE ALSO 

uname(l) in the 3B2 Computer System User Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, —1 is 
returned and errno is set to indicate the error. 
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NAME 

unlink — remove directory entry 

SYNOPSIS 

int unlink (path) 
char *path; 


DESCRIPTION 

Unlink removes the directory entry named by the path name pointed to be 
path. 

The named tile is unlinked unless one or more of the following are true: 


[ENOTDIR] 

[ENOENT] 

[EACCES] 

[EACCES] 


A component of the path prefix is not a directory. 

The named file does not exist. 

Search permission is denied for a component of the path 
prefix. 

Write permission is denied on the directory containing the link 
to be removed. 


[EPERM] 

[EBUSY] 

[ETXTBSY] 

[EROFS1 

[EFAULT] 


The named file is a directory and the effective user ID of the 
process is not super-user. 

The entry to be unlinked is the mount point for a mounted file 
system. 

The entry to be unlinked is the last link to a pure procedure 
(shared text) file that is being executed. 

The directory entry to be unlinked is part of a read-only file 
system. 

Path points outside the process’s allocated address space. 


When all links to a file have been removed and no process has the file open, the 
space occupied by the file is freed and the file ceases to exist. If one or more 
processes have the file open when the last link is removed, the removal is post- 
poned until all references to the file have been closed. 


SEE ALSO 

close(2), link(2), open(2). 

rm(l) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

ustat — get file system statistics 
SYNOPSIS 

#include <sys/types.h> 

#include <ustat.h> 

int ustat (dev, buf) 
int dev; 

struct ustat *buf; 

DESCRIPTION 

Ustat returns information about a mounted file system. Dev is a device number 
identifying a device containing a mounted file system. Buf is a pointer to a 
ustat structure that includes to following elements: 

daddr t f tfree; /* Total free blocks */ 

ino_t f_tinode; /* Number of free inodes */ 

char f_fname[6]; /* Filsys name */ 

char f_fpack[6]; /» Filsys pack name */ 

Ustat will fail if one or more of the following are true: 

[EINVAL] Dev is not the device number of a device containing a 

mounted file system. 

[EFAULT] Buf points outside the process’s allocated address space. 

SEE ALSO 

stat(2), fs(4). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

utime — set file access and modification times 
SYNOPSIS 

#include <sys/types.h> 
int utime (path, times) 
char *path; 
struct utimbuf “times; 

DESCRIPTION 

Path points to a path name naming a file. Utime sets the access and 
modification times of the named file. 

If times is NULL, the access and modification times of the file are set to the 
current time. A process must be the owner of the file or have write permission 
to use utime in this manner. 

If times is not NULL, times is interpreted as a pointer to a utimbuf structure 
and the access and modification times are set to the values contained in the 
designated structure. Only the owner of the file or the super-user may use 
utime this way. 

The times in the following structure are measured in seconds since 00:00:00 
GMT, Jan. 1, 1970. 

struct utimbuf ( 

time t actime; /* access time */ 

time t modtime; /* modification time */ 

}; 

Utime will fail if one or more of the following are true: 

[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EACCES] Search permission is denied by a component of the path 

prefix. 

[EPERMl The effective user ID is not super-user and not the owner of 

the file and times is not NULL. 

[EACCES] The effective user ID is not super-user and not the owner of 

the file and times is NULL and write access is denied. 

[EROFS] The file system containing the file is mounted read-only. 

[EFAULT] Times is not NULL and points outside the process’s allocated 

address space. 

[EFAULT] Path points outside the process’s allocated address space. 

SEE ALSO 

stat(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 


10/84 


- 1 - 


10/84 



WAIT(2) 


WAIT (2) 


NAME 

wait — wait for child process to stop or terminate 

SYNOPSIS 

int wait (statjoc) 
int *stat_loc; 

int wait ((int «)0) 

DESCRIPTION 

Wait suspends the calling process until until one of the immediate children ter- 
minates or until a child that is being traced stops, because it has hit a break 
point. The wait system call will return prematurely if a signal is received and 
if a child process stopped or terminated prior to the call on wait , return is 
immediate. 

If statjoc (taken as an integer) is non-zero, 16 bits of information called 
status are stored in the low order 16 bits of the location pointed to by stat loc. 
Status can be used to differentiate between stopped and terminated child 
processes and if the child process terminated, status identifies the cause of ter- 
mination and passes useful information to the parent. This is accomplished in 
the following manner: 

If the child process stopped, the high order 8 bits of status will contain 
the number of the signal that caused the process to stop and the low 
order 8 bits will be set equal to 0177. 

If the child process terminated due to an exit call, the low order 8 bits 
of status will be zero and the high order 8 bits will contain the low 
order 8 bits of the argument that the child process passed to exit ; see 
exit (2) . 

If the child process terminated due to a signal, the high order 8 bits of 
status will be zero and the low order 8 bits will contain the number of 
the signal that caused the termination. In addition, if the low order 
seventh bit (i.e., bit 200) is set, a “core image” will have been pro- 
duced; see signal (2) . 

If a parent process terminates without waiting for its child processes to ter- 
minate, the parent process ID of each child process is set to 1. This means the 
initialization process inherits the child processes; see intro (2). 

Wait will fail and return immediately if one or more of the following are true: 

[ECHILD] The calling process has no existing unwaited-for child 

processes. 

[EFAULT] Stat joc points to an illegal address. 

SEE ALSO 

exec (2), exit (2), fork (2), intro (2), pause (2), ptrace(2), signal (2). 

WARNING 

See WARNING in signal ( 2). 

DIAGNOSTICS 

If wait returns due to the receipt of a signal, a value of —1 is returned to the 
calling process and errno is set to EINTR. If wait returns due to a stopped or 
terminated child process, the process ID of the child is returned to the calling 
process. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 
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NAME 

write — write on a file 
SYNOPSIS 

int write (Sides, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe sys- 
tem call. 

Write attempts to write nbyte bytes from the buffer pointed to by buf to the 
file associated with the fildes. 

On devices capable of seeking, the actual writing of data proceeds from the 
position in the file indicated by the file pointer. Upon return from write, the 
file pointer is incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the 
current position. The value of a file pointer associated with such a device is 
undefined. 

If the O APPEND flag of the file status flags is set, the file pointer will be set to 
the end of the file prior to each write. 

For regular files, if the O SYNC flag of the file status flags is set, the write will 
not return until both the file data and file status have been physically updated. 
This function is for special applications that require extra reliablity at the cost 
of performance. Also, for block special files, if this flag is set, the write will not 
return until the data has been physically updated. 

Write will fail and the file pointer will remain unchanged if one or more of the 
following are true: 

[EBADFl Fildes is not a valid file descriptor open for writing. 

[EP1PE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for 
reading by any process. 

[EFBIG] An attempt was made to write a file that exceeds the process’s 

file size limit or the maximum file size. See ulimit ( 2). 

[EFAULT] Buf points outside the process’s allocated address space. 

[EINTR] A signal was caught during the write system call. 

If a write requests that more bytes be written than there is room for (e.g., the 
ulimit (see ulimit ( 2)) or the physical end of a medium), only as many bytes as 
there is room for will be written. For example, suppose there is space for 20 
bytes more in a file before reaching a limit. A write of 512-bytes will return 
20. The next write of a non-zero number of bytes will give a failure return 
(except as noted below). 

If the file being written is a pipe (or FIFO) and the 0_NDELAY flag of the file 
flag word is set, then write to a full pipe (or FIFO) will return a count of 0. 
Otherwise (ON DELAY clear), writes to a full pipe (or FIFO) will block until 
space becomes available. 

SEE ALSO 

creat (2), dup (2), fcntl (2), lseek(2), open (2), pipe (2), ulimit (2). 

DIAGNOSTICS 

Upon successful completion the number of bytes actually written is returned. 
Otherwise, — 1 is returned and errno is set to indicate the error. 
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NAME 

intro — introduction to subroutines and libraries 

SYNOPSIS 

#include <stdio.h> 

#include <math.h> 

DESCRIPTION 

This section describes functions found in various libraries, other than those 
functions that directly invoke UNIX system primitives, which are described in 
Section 2 of this volume. Certain major collections are identified by a letter 
after the section number: 

(3C) These functions, together with those of Section 2 and those marked 
(3S), constitute the Standard C Library libc, which is automatically 
loaded by the C compiler, cc( 1). The link editor ld( 1) searches this 
library under the — lc option. Declarations for some of these functions 
may be obtained from #include files indicated on the appropriate pages. 
(3S) These functions constitute the “standard I/O package” (see stdio( 3S)). 
These functions are in the library libc, already mentioned. Declarations 
for these functions may be obtained from the #include file <stdio.h>. 
(3M) These functions constitute the Math Library, libm. They are automati- 
cally loaded as needed by the FORTRAN compiler /77( 1). They are not 
automatically loaded by the C compiler, cc(l); however, the link editor 
searches this library under the — lm option. Declarations for these func- 
tions may be obtained from the #include file <math.h>. Several gen- 
erally useful mathematical constants are also defined there (see 
math (5)). 

(3X) Various specialized libraries. The files in which these libraries are found 
are given on the appropriate pages. 

(3F) These functions constitute the FORTRAN intrinsic function library, 
libF77. These functions are automatically available to the FORTRAN 
programmer and require no special invocation of the compiler. 

DEFINITIONS 

A character is any bit pattern able to fit into a byte on the machine. The null 
character is a character with value 0, represented in the C language as ’\0\ A 
character array is a sequence of characters. A null -terminated character 
array is a sequence of characters, the last of which is the null character. A 
string is a designation for a null -terminated character array. The null string 
is a character array containing only the null character. A NULL pointer is the 
value that is obtained by casting 0 into a pointer. The C language guarantees 
that this value will not match that of any legitimate pointer, so many functions 
that return pointers return it to indicate an error. NULL is defined as 0 in 
<stdio.h>; the user can include an appropriate definition if not using 
<stdio.h>. 

Many groups of FORTRAN intrinsic functions have generic function names that 
do not require explicit or implicit type declaration. The type of the function 
will be determined by the type of its argument (s). For example, the generic 
function max will return an integer value if given integer arguments (maxO), a 
real value if given real arguments (.amaxl), or a double-precision value if given 
double-precision arguments ( dmaxl ). 

FILES 

/lib/libc.a 

/lib/libm.a 

/usr/lib/libF77.a 
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SEE ALSO 

intro(2), stdio(3S), math(5). 

ar(l), Id ( 1 ) , nm(l) in the 3B2 Computer Software Generation System Utili- 
ties. 

cc(l), lint(l) in the 3B2 Computer C Programming Language Utilities. 
f77(l) in the 3B2 Computer FORTRAN Programming Language Utilities. 

DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return the conven- 
tional values 0 or ±HUGE (the largest-magnitude single-precision floating-point 
numbers; HUGE is defined in the <math.h> header file) when the function is 
undefined for the given arguments or when the value is not representable. In 
these cases, the external variable errno (see intro (2 )) is set to the value EDOM 
or ERANGE. As many of the FORTRAN intrinsic functions use the routines 
found in the Math Library, the same conventions apply. 

WARNING 

Many of the functions in the libraries call and/or refer to other functions and 
external variables described in this section and in section 2 ( System Calls). If 
a program inadvertantly defines a function or external variable with the same 
name, the presumed library version of the function or external variable may not 
be loaded. The lint 1 1) program checker reports name conflicts of this kind as 
“multiple declarations” of the names in question. Definitions for sections 2, 3C, 
and 3S are checked automatically. Other definitions can be included by using 
the —I option (for example, — 1 m includes definitions for the Math Library, sec- 
tion 3M). Use of lint is highly recommended. 
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NAME 

a641, 164a — convert between long integer and base-64 ASCII string 

SYNOPSIS 

long a641 (s) 
char *s; 

char »164a (1) 
long 1; 

DESCRIPTION 

These functions are used to maintain numbers stored in base-64 ASCII charac- 
ters. This is a notation by which long integers can be represented by up to six 
characters; each character represents a “digit” in a radix-64 notation. 

The characters used to represent “digits” are . for 0, / for 1, 0 through 9 for 
2—11, A through Z for 12—37, and a through z for 38—63. 

A641 takes a pointer to a null-terminated base-64 representation and returns a 
corresponding long value. If the string pointed to by s contains more than six 
characters, a64l will use the first six. 

L64a takes a long argument and returns a pointer to the corresponding base-64 
representation. If the argument is 0, 164a returns a pointer to a null string. 

BUGS 

The value returned by 164a is a pointer into a static buffer, the contents of 
which are overwritten by each call. 
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ABORT (3C) 


NAME 

abort - generate an IOT fault 

SYNOPSIS 

int abort ( ) 

DESCRIPTION 

Abort first closes all open files if possible, then causes an IOT signal to be sent 
to the process. This usually results in termination with a core dump. 

It is possible for abort to return control if SIGIOT is caught or ignored, in which 
case the value returned is that of the kill (2) system call. 

SEE ALSO 

exit (2), kill (2), signal (2). 

sdb(l) in the 3B2 Computer Extended Software Generation System Utilities. 
DIAGNOSTICS 

If SIGIOT is neither caught nor ignored, and the current directory is writable, a 
core dump is produced and the message “abort — core dumped” is written by 
the shell. 
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ABS (3C) 


NAME 

abs — return integer absolute value 

SYNOPSIS 

int abs (i) 
int i; 

DESCRIPTION 

Abs returns the absolute value of its integer operand. 

SEE ALSO 

floor(3M). 

BUGS 

In two’s-complement representation, the absolute value of the negative integer 
with largest magnitude is undefined. Some implementations trap this error, but 
others simply ignore it. 
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NAME 

bsearch — binary search a sorted table 

SYNOPSIS 

#include <search.h> 

char »bsearch ((char ») key, (char *) base, nel, sizeof (*key), compar) 

unsigned nel; 

int (*compar)( ); 

DESCRIPTION 

Bsearch is a binary search routine generalized from Knuth (6.2.1) Algorithm 
B. It returns a pointer into a table indicating where a datum may be found. 
The table must be previously sorted in increasing order according, to a provided 
comparison function. Key points to a datum instance to be sought in the table. 
Base points to the element at the base of the table. Nel is the number of ele- 
ments in the table. Compar is the name of the comparison function, which is 
called with two arguments that point to the elements being compared. The 
function must return an integer less than, equal to, or greater than zero as 
accordinly the first argument is to be considered less than, equal to, or greater 
than the second. 

EXAMPLE 

The example below searches a table containing pointers to nodes consisting of a 
string and its length. The table is ordered alphabetically on the string in the 
node pointed to by each entry. 

This code fragment reads in strings and either finds the corresponding node and 
prints out the string and its length, or prints an error message. 

#include <stdio.h> 

#include <search.h> 

#define TABSIZE 1000 

struct node { /* these are stored in the table */ 

char ‘string; 
int length; 

}; 

struct node tabletTABSIZE]; /* table to be searched */ 


struct node »node_ptr, node; 

int node_compare( ); /» routine to compare 2 nodes »/ 

char str_space[20]; /* space to read string into */ 


node.string = strspace; 

while (scanf("%s", node.string) != EOF) { 

node_ptr = (struct node *) bsearch ((char *)(&node), 
(char *)table, TABSIZE, 
sizeof (struct node), node_compare); 
if (node_ptr != NULL) { 

(void) printf ("string = %20s, length = %d\n", 
node_ptr— > string, node_ptr— > length) ; 

) else ( 

(void) printf ("not found: %s\n", node.string); 
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/» 

This routine compares two nodes based on an 
alphabetical ordering of the string field. 

*/ 

int 

node_compare(nodel, node2) 
struct node *nodel, *node2; 

return strcmpCnodel— > string, node2— > string); 

} 

NOTES 

The pointers to the key and the element at the base of the table should be of 
type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may 
be contained in the elements in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should be 
cast into type pointer-to-element. 

SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned if the key cannot be found in the table. 
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NAME 

clock — report CPU time used 

SYNOPSIS 

long clock ( ) 

DESCRIPTION 

Clock returns the amount of CPU time (in microseconds) used since the first 
call to clock. The time reported is the sum of the user and system times of the 
calling process and its terminated child processes for which it has executed 
wait (2) or system (3S) . 

The resolution of the clock is 10 milliseconds on AT&T Technologies 3B com- 
puter processors. 

SEE ALSO 

times (2), wait (2), system (3S). 

BUGS 

The value returned by clock is defined in microseconds for compatibility with 
systems that have CPU clocks with much higher resolution. Because of this, 
the value returned will wrap around after accumulating only 2147 seconds of 
CPU time (about 36 minutes). 
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, tolower, Joupper, Jolower, toascii - translate characters 


NAME 

toupper 

SYNOPSIS 

#include <ctype.h> 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toascii (c) 
int c; 

DESCRIPTION . the ranee of eetc(3S): the integers from 

Toupper and tolower have as domain the range g lower . case letter, the 

-1 Through 255. If "» e ,T“« .rgunren. of ,olo»er 

result is the correspcndmg upper case correspondi ng lower-case letter, 

renresents an upper-case letter, the resuu is ^ , 1 , 

All other arguments in the domain are returned unchanged. 

H tn [ ower are macros that accomplish the same thing 
The macros Joupper and Jolower , are and are faster . toupper 

as toupper and tolower but ave res . result is the corresponding 

requires a lower-case letter as In upper-case letter as its 

upper-case letter. The macr _ lower-case letter Arguments outside 

argument; its result is the corresponding lower-case letter. g 

the domain cause undefined results. 


SEE ALSO 

ctype(3C), getc(3S). 
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NAME 

crypt, setkey, encrypt — generate hashing encryption 
SYNOPSIS 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, fake) 
char *block; 
int fake; 

DESCRIPTION 

Crypt is the password encryption function. It is based on a one way hashing 
encryption algorithm with variations intended (among other things) to frustrate 
use of hardware implementations of a key search. 

Key is a user’s typed password. Salt is a two-character string chosen from the 
set [a-zA-ZO-9./]; this string is used to perturb the hashing algorithm in one of 
4096 different ways, after which the password is used as the key to encrypt 
repeatedly a constant string. The returned value points to the encrypted pass- 
word. The first two characters are the salt itself. 

The setkey and encrypt entries provide (rather primitive) access to the actual 
hashing algorithm. The argument of setkey is a character array of length 64 
containing only the characters with numerical value 0 and 1. If this string is 
divided into groups of 8, the low-order bit in each group is ignored; this gives a 
56-bit key which is set into the machine. This is the key that will be used with 
the hashing algorithm to encrypt the string block with the function encrypt. 

The argument to the encrypt entry is a character array of length 64 containing 
only the characters with numerical value 0 and 1. The argument array is 
modified in place to a similar array representing the bits of the argument after 
having been subjected to the hashing algorithm using the key set by setkey. 
Fake is not used and is ignored, but should be present if lint{ 1) is used. 

SEE ALSO 

getpass(3C), passwd(4). 

login(l), passwd(l) in the 3B2 Computer System User Reference Manual. 

BUGS 

The return value points to static data that are overwritten by each call. 
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NAME 

ctermid — generate file name for terminal 

SYNOPSIS 

#include <stdio.h> 
char »ctermid (s) 
char *s; 

DESCRIPTION . , r 

Ctermid generates the path name of the controlling terminal for the current 

process, and stores it in a string. 

If j is a NULL pointer, the string is stored in an internal static area, the con- 
tents of which are overwritten at the next call to ctermid, and the address of 
which is returned. Otherwise, 5 is assumed to point to a character array of at 
least L_ctermid elements; the path name is placed in this array and the value of 
s is returned. The constant L_ctermid is defined in the <stdio.h> header file. 


The difference between ctermid and ttyname { 3C) is that ttyname must be 
handed a file descriptor and returns the actual name of the terminal associated 
with that file descriptor, while ctermid returns a string (/dev/tty) that will 
refer to the terminal if used as a file name. Thus ttyname is useful only if the 
process already has at least one file open to a terminal. 


SEE ALSO 

ttyname(3C). 
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NAME 

ctime, localtime, gmtime, asctime, tzset — convert date and time to string 

SYNOPSIS 

#include <time.h> 

char »ctime (clock) 
long * clock; 

struct tm *localtime (clock) 
long *clock; 

struct tm *gmtime (clock) 
long *clock; 

char *asctime (tm) 
struct tm *tm; 

extern long timezone; 
extern int daylight; 
extern char *tzname[2l; 
void tzset ( ) 

DESCRIPTION 

Ctime converts a long integer, pointed to by clock, representing the time in 
seconds since 00:00:00 GMT, January 1, 1970, and returns a pointer to a 26- 
character string in the following form. All the fields have constant width. 

Sun Sep 16 01:03:52 1973\n\0 

Localtime and gmtime return pointers to “tm” structures, described below. 
Localtime corrects for the time zone and possible Daylight Savings Time; 
gmtime converts directly to Greenwich Mean Time (GMT), which is the time 
the UNIX system uses. 

Asctime converts a “tm” structure to a 26-character string, as shown in the 
above example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the “tm” structure, are in 
the <time.h> header file. The structure declaration is: 

struct tm { 

int tm_sec; 
int tm_min; 
int tmhour; 
int tmmday; 
int tmmon; 
int tm_year; 
int tmwday; 
int tm_yday; 
int tm_isdst; 

}; 

Tmjsdst is non-zero if Daylight Savings Time is in effect. 

The external long variable timezone contains the difference, in seconds, between 
GMT and local standard time (in EST, timezone is 5*60»60); the external vari- 
able daylight is non-zero if and only if the standard U.S.A. Daylight Savings 
Time conversion should be applied. The program knows about the peculiarities 
of this conversion in 1974 and 1975; if necessary, a table for these years can be 
extended. 

If an environment variable named TZ is present, asctime uses the contents of 
the variable to override the default time zone. The value of TZ must be a 


/* seconds (0-59) »/ 

/» minutes (0 - 59) */ 

/» hours (0 - 23) */ 

/* day of month (1 - 31) */ 

/» month of year (0 - 11) */ 
/* year — 1900 */ 

/* day of week (Sunday = 0) */ 

/* day of year (0 - 365) */ 


10/84 


- 1 - 


10/84 



CTIMEC3C) 


(C Programming Language Utilities) 


CTIME(3C) 


three letter time zone name, followed by a number representing the difference 
betwein lo C rtime and Greenwich Mean Time in hours, followed by an 
optional three-letter name for a daylight time zone. 

for New Jersey would be EST5EDT. The effects of setting TZ are thus to 
change the values of the external variables timezone and daylight ; m additio , 
the time zone names contained in the external variab e 

char *tznamel2l = l "EST", "EDT }; 

are set from the environment variable TZ. The function tzset sets these exter- 
nal variables from TZ; tzset is called by asctime and may also be called exp 

citly by the user. 

Note that in most installations, TZ is set by default when the user logs on, to a 
value in the local /etc/profile file (see profiled 4)). 

SEE AL ^ime(2), getenv(3C), profiled), environ(5). 


BUGS 


The return values point to static 


data whose content is overwritten by each call. 
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NAME 

isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, 
isgraph, iscntrl, isascii — classify characters 

SYNOPSIS 

#include <ctype.h> 

int isalpha (c) 
int c; 


DESCRIPTION 

These macros classify character-coded integer values by table lookup. Each is 
a predicate returning nonzero for true, zero for false. Isascii is defined on all 
integer values; the rest are defined only where isascii is true and on the single 
non-ASCII value EOF (—1 — see stdio( 3S)). 

isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 

isdigit c is a digit [0-9]. 

isxdigit c is a hexadecimal digit [0-9], [A-F] or [a-f], 

isalnum c is an alphanumeric (letter or digit). 

isspace c is a space, tab, carriage return, new-line, vertical tab, or 

form-feed. 

ispunct c is a punctuation character (neither control nor 

alphanumeric). 

isprint c is a printing character, code 040 (space) through 0176 

(tilde). 

isgraph c is a printing character, like isprint except false for space. 

iscntrl c is a delete character (0177) or an ordinary control character 

(less than 040). 

isascii c is an ASCII character, code less than 0200. 

SEE ALSO 

stdio(3S), ascii(5). 

DIAGNOSTICS 

If the argument to any of these macros is not in the domain of the function, the 
result is undefined. 
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NAME . , 

cuserid - get character login name of the user 


SYNOPSIS 

#include <stdio.h> 

char *cuserid (s) 
char *s; 


DESCRIPTION^ rates a character . str i n g representation of the login name that the 
owner of the current process is logged in under. If 5 is a NULL pointer . th s 
representation is generated in an internal static area, the address 5 of which s 
returned Otherwise, 5 is assumed to point to an array of at least L_cuserid 
characters; the representation is left in this array. The constant L_cusend is 
defined in the <stdio.h> header file. 


DIAGNOSTICS^^ canno t be found, cuserid returns a NULL pointer; if J is not a 

NULL pointer, a null character (\0) will be placed at slOJ. 


SEE ALSO 

getlogin(3C), getpwent(3C). 
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NAME 

dial — establish an out-going terminal line connection 

SYNOPSIS 

#include <dial.h> 

int dial (call) 

CALL call; 

void undial (fd) 
int fd; 

DESCRIPTION 

Dial returns a file-descriptor for a terminal line open for read/write. The argu- 
ment to dial is a CALL structure (defined in the <dial.h> header file). 

When finished with the terminal line, the calling program must invoke undial 
to release the semaphore that has been set during the allocation of the terminal 
device. 

The definition of CALL in the <dial.h> header file is: 
typedef struct ( 


struct termio *attr; 

/» pointer to termio attribute struct */ 

int 

baud; 

/» transmission data rate */ 

int 

speed; 

/* 212A modem: low=300, high=1200 */ 

char 

*line; 

/» device name for out-going line */ 

char 

*telno; 

/* pointer to tel-no digits string */ 

int 

modem; 

/» specify modem control for direct lines */ 

char 

*device; 

/*Will hold the name of the device used 
to make a connection */ 

int 

devjen; 

/* The length of the device used to make 
connection */ 


) CALL; 

The CALL element speed is intended only for use with an outgoing dialed call, 
in which case its value should be either 300 or 1200 to identify the 113A 
modem, or the high- or low-speed setting on the 212A modem. Note that the 
113A modem or the low-speed setting of the 21 2A modem will transmit at any 
rate between 0 and 300 bits per second. However, the high-speed setting of the 
21 2 A modem transmits and receivers at 1200 bits per secound only. The CALL 
element baud is for the desired transmission baud rate. For example, one 
might set baud to 110 and speed to 300 (or 1200). However, if speed set to 
1200 baud must be set to high (1200). 

If the desired terminal line is a direct line, a string pointer to its device-name 
should be placed in the line element in the CALL structure. Legal values for 
such terminal device names are kept in the L-devices file. In this case, the 
value of the baud element need not be specified as it will be determined from 
the L-devices file. 

The telno element is for a pointer to a character string representing the tele- 
phone number to be dialed. Such numbers may consist only of symbols 
described on the acu( 7). The termination symbol will be supplied by the dial 
function, and should not be included in the telno string passed to dial in the 
CALL structure. 

The CALL element modem is used to specify modem control for direct lines. 
This element should be non-zero if modem control is required. The CALL ele- 
ment attr is a pointer to a termio structure, as defined in the termio.h header 
file. A NULL value for this pointer element may be passed to the dial function, 
but if such a structure is included, the elements specified in it will be set for 
the outgoing terminal line before the connection is established. This is often 
important for certain attributes such as parity and baud-rate. 
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The CALL element device is used to hold the device name 
lishes the connection. 

The CALL element dev Jen is the length of the device nam 
the array device. 


(cul..) that estab- 
that is copied into 


FILES 


/usr/lib/ uucp/L-devices 
/usr/spool/ uucp/LCK. . tty -device 


SEE ALSO 

alarm(2), read ^, wnteC2K Administration Utilities Guide. 

DIAGNOSTICS indicating the reason for the failure will be 

S»,“ ur SS.*— - ■- - « “- 1 ,n th ‘ 


<dial.h> header file. 


INTRPT 

d_hung 

NO_ANS 

ILL_BD 

A_PROB 

l_prob 

NOLdv 

DV_NT_A 

DV_NT_K 

NO_BD_A 

NO BD_K 


-1 

-2 

-3 

-4 


*/ 


-5 

-6 

-7 

-8 

-9 

-10 

-11 


/» interrupt occurred */ 

/. dialer hung (no return from write) 

/» no answer within 10 seconds */ 

/* illegal baud-rate */ 

/* acu problem (openO failure) */ 

/* line problem (openO failure) */ 

/. can’t open LDEVS file */ 

/» requested device not available */ 

/* requested device not known */ 

/. no device available at requested baud */ 
/. no device known at requested baud */ 

<dial.h> header file automatically includes the <termio.h> 

“Th -nds The alarm 
simply delete the LCK.. entry j( 9 ) or write ( 2) system call, 

may ’go off while .he use, program ^ „ be ’ around for 

r’tir r more,’"”™, returns from read s should be checked fo, 
(errno = = EINTR) , and the read possibly reissued. 


WARNINGS 

Including the 
header file. 


BUGS 
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NAME 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, 
lcong48 — generate uniformly distributed pseudo-random numbers 
SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi[3l; 

long lrand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi[3l; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi[3l; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seedl6v) 
unsigned short seedl6v[3l; 

void lcong48 (param) 
unsigned short param[7l; 

DESCRIPTION 

This family of functions generates pseudo-random numbers using the well- 
known linear congruential algorithm and 48-bit integer arithmetic. 

Functions drand48 and erand48 return non-negative double-precision floating- 
point values uniformly distributed over the interval [0.0, 1.0). 

Functions lrand48 and nrand48 return non-negative long integers uniformly 
distributed over the interval [0, 2 31 ). 

Functions mrand48 and jrand48 return signed long integers uniformly distri- 
buted over the interval [— 2 31 , 2 31 ). 

Functions srand48, seed48 and lcong48 are initialization entry points, one of 
which should be invoked before either drand48, lrand48 or mrand48 is called. 
(Although it is not recommended practice, constant default initializer values 
will be supplied automatically if drand48, lrand48 or mrand48 is called 
without a prior call to an initialization entry point.) Functions erand48, 
nrand48 and jrand48 do not require an initialization entry point to be called 
first. 

All the routines work by generating a sequence of 48-bit integer values, Xj, 
according to the linear congruential formula 

X n + 1 (@X n "He) mod m /t ^ 0 . 

The parameter m=2 48 ; hence 48-bit integer arithmetic is performed. Unless 
lcong48 has been invoked, the multiplier value a and the addend value c are 
given by 

a = 5DEECE66D 16 = 273673 1 63 1 55 8 
c = Bi6 = 1 3 8 . 

The value returned by any of the functions drand48, erand48, lrand48, 
nrand48, mrand48 or jrand48 is computed by first generating the next 48-bit 
Xj in the sequence. Then the appropriate number of bits, according to the type 
of data item to be returned, are copied from the high-order (leftmost) bits of 
Xj and transformed into the returned value. 
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The functions drand48, lrand48 and mrand48 store the last 48-bit X ,• gen- 
erated in an internal buffer; that is why they must be initialized prior to being 
invoked. The functions erand48, nrand48 and jrand48 require the calling pro- 
gram to provide storage for the successive Xj values in the array specified as an 
argument when the functions are invoked. That is why these routines do not 
have to be initialized; the calling program merely has to place the desired ini- 
tial value of Xi into the array and pass it as an argument. By using different 
arguments, functions erand48, nrand48 and jrand48 allow separate modules of 
a large program to generate several independent streams of pseudo-random 
numbers, i.e., the sequence of numbers in each stream will not depend upon 
how many times the routines have been called to generate numbers for the 
other streams. 

The initializer function srand48 sets the high-order 32 bits of Xj to the 32 bits 
contained in its argument. The low-order 16 bits of Xj are set to the arbitrary 
value 330Eifi. 

The initializer function seed48 sets the value of Xj to the 48-bit value specified 
in the argument array. In addition, the previous value of Xj is copied into a 
48-bit internal buffer, used only by seed48, and a pointer to this buffer is the 
value returned by seed48. This returned pointer, which can just be ignored if 
not needed, is useful if a program is to be restarted from a given point at some 
future time — use the pointer to get at and store the last Xj value, and then 
use this value to reinitialize via seed48 when the program is restarted. 

The initialization function lcong48 allows the user to specify the initial Xj, the 
multiplier value a, and the addend value c. Argument array elements 
param[0-2] specify Xj, param[3-5] specify the multiplier a, and param[6] 
specifies the 16-bit addend c. After lcong48 has been called, a subsequent call 
to either srand48 or seed48 will restore the “standard” multiplier and addend 
values, a and c , specified on the previous page. 

NOTES 

The routines are coded in portable C. The source code for the portable version 
can even be used on computers which do not have floating-point arithmetic. In 
such a situation, functions drand48 and erand48 do not exist; instead, they are 
replaced by the two new functions below. 

long irand48 (m) 
unsigned short m; 

long krand48 (xsubi, m) 
unsigned short xsubi[3], m; 

Functions irand48 and krand48 return non-negative long integers uniformly 
distributed over the interval [0, m — 1]. 

SEE ALSO 

rand(3C). 
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NAME 


ecvt, fcvt, gcvt - convert floating-point number to string 


SYNOPSIS^ (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *fcvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, ‘decpt, ‘sign; 

char »gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 

DESCRIPTION terminated string of ndigit digits and returns a 

Ecvt converts value to a null-term 0 un i ess the value is zero. The 

pointer thereto. The hl g h ‘ or 'position of the decimal point relative to the 

££ “ b> 
tivn is non-zero, otherwise it is zero. 

^ t t u correct digit has been rounded for 

.T,h, ^ - ** — * 

buf and returns buf. It attempts to p read ., for printing. A minus 

S„“r W - be included as pa,, of the returned 

string. Trailing zeros are suppressed. 

SEE ALSO 

printf(3S). 

BUGS The values returned by ecvt and fcvt point to a single static data array whose 
mntent is overwritten by each call. 
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NAME 

end, etext, edata — last locations in program 

SYNOPSIS 

extern end; 
extern etext; 
extern edata; 

DESCRIPTION 

These names refer neither to routines nor to locations with interesting contents. 
The address of etext is the first address above the program text, edata above 
the initialized data region, and end above the uninitialized data region. 

When execution begins, the program break (the first location beyond the data) 
coincides with end, but the program break may be reset by the routines of 
brk( 2), malloc(3C) , standard input/output (stdio( 3S)), the profile (— p) 
option of cc( 1), and so on. Thus, the current value of the program break 
should be determined by sbrk(O) (see brk(2)) . 

SEE ALSO 

brk(2), malloc(3C), stdio(3S). 

cc(l) in the 3B2 Computer C Programming Language Utilities. 
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NAME 

fclose, fflush — close or flush a stream 

SYNOPSIS 

#inc!ude <stdio.h> 

int fclose (stream) 

FILE ‘Stream; 

int fflush (stream) 

FILE ‘Stream; 

DESCRIPTION 

Fclose causes any buffered data for the named stream to be written out, and 
the stream to be closed. 

Fclose is performed automatically for all open files upon calling exit (2). 

Fflush causes any buffered data for the named stream to be written to that file. 
The stream remains open. 

SEE ALSO 

close (2), exit (2), fopen(3S), setbuf(3S). 

DIAGNOSTICS 

These functions return 0 for success, and EOF if any error (such as trying to 
write to a file that has not been opened for writing) was detected. 
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NAME 

ferror, feof, clearerr, fileno — stream status inquiries 

SYNOPSIS 

#include <stdio.h> 

int ferror (stream) 

FILE ‘stream; 

int feof (stream) 

FILE ‘stream; 

void clearerr (stream) 

FILE ‘stream; 

int iileno (stream) 

FILE ‘stream; 

DESCRIPTION 

Ferror returns non-zero when an I/O error has previously occurred reading 
from or writing to the named stream, otherwise zero. 

Feof returns non-zero when EOF has previously been detected reading the 
named input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero on the named 
stream . 

Fileno returns the integer file descriptor associated with the named stream ; see 
open (2) . 

NOTES 

All these functions are implemented as macros; they cannot be declared or 
redeclared. 

SEE ALSO 

open (2), fopen(3S). 
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NAME 

fopen, freopen, fdopen — open a stream 

SYNOPSIS 

#include <stdio.h> 

FILE *fopen (file-name, type) 
char *file-name, ‘type; 

FILE ‘freopen (file-name, type, stream) 
char ‘file-name, ‘type; 

FILE ‘stream; 

FILE ‘fdopen (Aides, type) 
int tildes; 
char ‘type; 

DESCRIPTION 

Fopen opens the file named by file-name and associates a stream with it. 
Fopen returns a pointer to the FILE structure associated with the stream. 

File-name points to a character string that contains the name of the file to be 
opened. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 

"a" append; open for writing at end of file, or create for writing 

"r+" open for update (reading and writing) 

"w+" truncate or create for update 

"a+" append; open or create for update at end-of-file 

Freopen substitutes the named file in place of the open stream. The original 
stream is closed, regardless of whether the open ultimately succeeds. Freopen 
returns a pointer to the FILE structure associated with stream. 

Freopen is typically used to attach the preopened streams associated with stdin, 
stdout and stderr to other files. 

Fdopen associates a stream with a file descriptor. File descriptors are obtained 
from open, dup , creat, or pipe(2), which open files but do not return pointers 
to a FILE structure stream. Streams are necessary input for many of the Sec- 
tion 3S library routines. The type of stream must agree with the mode of the 
open file. 

When a file is opened for update, both input and output may be done on the 
resulting stream. However, output may not be directly followed by input 
without an intervening fseek or rewind, and input may not be directly followed 
by output without an intervening fseek, rewind, or an input operation which 
encounters end-of-file. 

When a file is opened for append (i.e., when type is "a" or "a+’O, it is impossi- 
ble to overwrite information already in the file. Fseek may be used to reposi- 
tion the file pointer to any position in the file, but when output is written to the 
file, the current file pointer is disregarded. All output is written at the end of 
the file and causes the file pointer to be repositioned at the end of the output. 
If two separate processes open the same file for append, each process may write 
freely to the file without fear of destroying output being written by the other. 
The output from the two processes will be intermixed in the file in the order in 
which it is written. 
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SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S). 
DIAGNOSTICS 

Fopen and freopen return a NULL pointer on failure. 


10/84 


- 2 - 


10/84 



FREAD (3S) 


(C Programming Language Utilities) 


FREAD (3S) 


NAME 

fread, fwrite — binary input/output 

SYNOPSIS 

#include <stdio.h> 

int fread (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE ‘stream; 

int fwrite (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE ‘Stream; 

DESCRIPTION 

Fread copies, into an array pointed to by ptr, nitems items of data from the 
named input stream, where an item of data is a sequence of bytes (not neces- 
sarily terminated by a null byte) of length size. Fread stops appending bytes if 
an end-of-file or error condition is encountered while reading stream, or if 
nitems items have been read. Fread leaves the file pointer in stream, if 
defined, pointing to the byte following the last byte read if there is one. Fread 
does not change the contents of stream. 

Fwrite appends at most nitems items of data from the array pointed to by ptr 
to the named output stream. Fwrite stops appending when it has appended 
nitems items of data or if an error condition is encountered on stream. Fwrite 
does not change the contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo-function sizeof 
specifies the length of an item pointed to by ptr. If ptr points to a data type 
other than char it should be cast into a pointer to char. 

SEE ALSO , N 

read(2), write(2), fopen(3S), getc(3S), gets(3S), printf(3S), putc(3S), 
puts(3S), scanf(3S). 

DIAGNOSTICS 

Fread and fwrite return the number of items read or written. If size or nitems 
is non-positive, no characters are read or written and 0 is returned by both 
fread and fwrite. 
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NAME 

frexp, ldexp, modf — manipulate parts of floating-point numbers 
SYNOPSIS 

double frexp (value, eptr) 
double value; 
int *eptr; 

double ldexp (value, exp) 
double value; 
int exp; 

double modf (value, iptr) 
double value, *iptr; 

DESCRIPTION 

Every non-zero number can be written uniquely as x * 2", where the “mantissa” 
(fraction) x is in the range 0.5 < |x| < 1.0, and the “exponent” n is an 
integer. Frexp returns the mantissa of a double value, and stores the exponent 
indirectly in the location pointed to by eptr. If value is zero, both results 
returned by frexp are zero. 

Ldexp returns the quantity value * 2 exp . 

Modf returns the signed fractional part of value and stores the integral part 
indirectly in the location pointed to by iptr. 

DIAGNOSTICS 

If ldexp would cause overflow, ±HUGE is returned (according to the sign of 
value), and errno is set to ERANGE. 

If ldexp would cause underflow, zero is returned and errno is set to ERANGE. 
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NAME 

fseek, rewind, ftell — reposition a file pointer in a stream 

SYNOPSIS 

#include <stdio.h> 

int fseek (stream, offset, ptrname) 

FILE *stream; 
long offset; 
int ptrname; 

void rewind (stream) 

FILE ‘Stream; 

long ftell (stream) 

FILE ‘stream; 

DESCRIPTION 

Fseek sets the position of the next input or output operation on the stream. 
The new position is at the signed distance offset bytes from the beginning, from 
the current position, or from the end of the file, according as ptrname has the 
value 0, 1, or 2. 

Rewind {stream) is equivalent to fseekistream, 0L, 0), except that no value is 
returned. 

Fseek and rewind undo any effects of ungetc{3S). 

After fseek or rewind , the next operation on a file opened for update may be 
either input or output. 

Ftell returns the offset of the current byte relative to the beginning of the file 
associated with the named stream. 

SEE ALSO 

lseek(2), fopen(3S), popen(3S), ungetc(3S). 

DIAGNOSTICS 

Fseek returns non-zero for improper seeks, otherwise zero. An improper seek 
can be, for example, an fseek done on a file that has not been opened via fopen\ 
in particular, fseek may not be used on a terminal, or on a file opened via 
popen{ 3S). 

WARNING 

Although on the UNIX system an offset returned by ftell is measured in bytes, 
and it is permissible to seek to positions relative to that offset, portability to 
non-UNIX systems requires that an offset be used by fseek directly. Arithmetic 
may not meaningfully be performed on such an offset, which is not necessarily 
measured in bytes. 
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NAME 

ftw — walk a file tree 

SYNOPSIS 

#include <ftw.h> 

int ftw (path, fn, depth) 
char *path; 
int (*fn) ( ); 
int depth; 

DESCRIPTION 

Ftw recursively descends the directory hierarchy rooted in path. For each 
object in the hierarchy, ftw calls fn, passing it a pointer to a null-terminated 
character string containing the name of the object, a pointer to a stat structure 
(see stat (2)) containing information about the object, and an integer. Possible 
values of the integer, defined in the <ftw.h> header file, are FTW F for a file, 
FTWJD for a directory, FTW_DNR for a directory that cannot be read, and 
FTWNS for an object for which stat could not successfully be executed. If the 
integer is FTW DNR, descendants of that directory will not be processed. If the 
integer is FTW_NS, the stat structure will contain garbage. An example of an 
object that would cause FTW NS to be passed to fn would be a file in a direc- 
tory with read but without execute (search) permission. 

Ftw visits a directory before visiting any of its descendants. 

The tree traversal continues until the tree is exhausted, an invocation of fn 
returns a nonzero value, or some error is detected within ftw (such as an I/O 
error) . If the tree is exhausted, ftw returns zero. If fn returns a nonzero value, 
ftw stops its tree traversal and returns whatever value was returned by fn. If 
ftw detects an error, it returns —1, and sets the error type in err no. 

Ftw uses one file descriptor for each level in the tree. The depth argument 
limits the number of file descriptors so used. If depth is zero or negative, the 
effect is the same as if it were 1 . Depth must not be greater than the number 
of file descriptors currently available for use. Ftw will run more quickly if 
depth is at least as large as the number of levels in the tree. 

SEE ALSO 

stat(2), malloc(3C). 

BUGS 

Because ftw is recursive, it is possible for it to terminate with a memory fault 
when applied to very deep file structures. 

It could be made to run faster and use less storage on deep structures at the 
cost of considerable complexity. 

Ftw uses malloci 3C) to allocate dynamic storage during its operation. If ftw is 
forcibly terminated, such as by longjmp being executed by fn or an interrupt 
routine, ftw will not have a chance to free that storage, so it will remain per- 
manently allocated. A safe way to handle interrupts is to store the fact that an 
interrupt has occurred, and arrange to have fn return a nonzero value at its 
next invocation. 
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NAME 

getc, getchar, fgetc, getw — get character or word from a stream 

SYNOPSIS 

#include <stdio.h> 

int getc (stream) 

FILE *stream; 

int getchar () 

int fgetc (stream) 

FILE ‘stream; 

int getw (stream) 

FILE ‘Stream; 

DESCRIPTION 

Getc returns the next character (i.e., byte) from the named input stream, as an 
integer. It also moves the file pointer, if defined, ahead one character in 
stream. Getchar is defined as getc (stdin) . Getc and getchar are macros. 

Fgetc behaves like getc, but is a function rather than a macro. Fgetc runs 
more slowly than getc, but it takes less space per invocation and its name can 
be passed as an argument to a function. 

Getw returns the next word (i.e., integer) from the named input stream. Getw 
increments the associated file pointer, if defined, to point to the next word. The 
size of a word is the size of an integer and varies from machine to machine. 
Getw assumes no special alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), scanf(3S). 
DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon an error. 
Because EOF is a valid integer, f error (3S) should be used to detect getw errors. 

WARNING 

If the integer value returned by getc, getchar, or fgetc is stored into a character 
variable and then compared against the integer constant EOF, the comparison 
may never succeed, because sign-extension of a character on widening to 
integer is machine-dependent. 

BUGS 

Because it is implemented as a macro, getc treats incorrectly a stream argu- 
ment with side effects. In particular, getc(*f++) does not work sensibly. 
Fgetc should be used instead. 

Because of possible differences in word length and byte ordering, files written 
using putw are machine-dependent, and may not be read using getw on a 
different processor. 
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NAME 

getcwd — get path-name of current working directory 
SYNOPSIS 

char »getcwd (buf, size) 
char »buf; 
int size; 

DESCRIPTION 

Getcwd returns a pointer to the current directory path name. The value of size 
must be at least two greater than the length of the path-name to be returned. 

If buf is a NULL pointer, getcwd will obtain size bytes of space using 
malloci 3C). In this case, the pointer returned by getcwd may be used as the 
argument in a subsequent call to free. 

The function is implemented by using popeni. 3S) to pipe the output of the 
pwd( 1) command into the specified string space. 

EXAMPLE 

char *cwd, »getcwd(); 


if ((cwd = getcwd((char *)NULL, 64)) == NULL) { 
perror(“pwd”); 
exit(l); 

} 

printf(“%s\n”, cwd); 

SEE ALSO 

malloc(3C), popen(3S). 

pwd(l) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if an error ocurrs in 
a lower-level function. 


10/84 


1 


10/84 



GETENV (3C) 


(C Programming Language Utilities) 


GETENV (3C) 


NAME 

getenv — return value for environment name 

SYNOPSIS 

char *getenv (name) 
char 'name; 

DESCRIPTION 

Getenv searches the environment list (see environ { 5)) for a string of the form 
name=value, and returns a pointer to the value in the current environment if 
such a string is present, otherwise a NULL pointer. 

SEE ALSO 

exec(2), putenv(3C), environ(5). 
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NAME 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent — get group file 
entry 

SYNOPSIS 

#include <grp.h> 

struct group ‘getgrent ( ) 

struct group ‘getgrgid (gid) 
int gid; 

struct group ‘getgrnam (name) 
char ‘name; 

void setgrent ( ) 
void endgrent ( ) 

struct group ‘fgetgrent (f) 

FILE *f; 

DESCRIPTION 

Getgrent , getgrgid and getgrnam each return pointers to an object with the fol- 
lowing structure containing the broken-out fields of a line in the /etc/group file. 
Each line contains a “group” structure, defined in the <grp.h> header file. 

struct group { 

char ‘gr name; /» the name of the group »/ 

char »gr_passwd; /* the encrypted group password */ 

int grjgid; /* the numerical group ID »/ 

char *»gr_mem; /* vector of pointers to member names »/ 

); 

Getgrent when first called returns a pointer to the first group structure in the 
file; thereafter, it returns a pointer to the next group structure in the file; so, 
successive calls may be used to search the entire file. Getgrgid searches from 
the beginning of the file until a numerical group id matching gid is found and 
returns a pointer to the particular structure in which it was found. Getgrnam 
searches from the beginning of the file until a group name matching name is 
found and returns a pointer to the particular structure in which it was found. 
If an end-of-file or an error is encountered on reading, these functions return a 
NULL pointer. 

A call to setgrent has the effect of rewinding the group file to allow repeated 
searches. Endgrent may be called to close the group file when processing is 
complete. 

Fgetgrent returns a pointer to the next group structure in the stream /, which 
matches the format of /etc/group. 

FILES 

/etc/group 
SEE ALSO 

getlogin(3C), getpwent(3C), group(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase the size of 
programs, not otherwise using standard I/O, more than might be expected. 

BUGS 

All information is contained in a static area, so it must be copied if it is to be 
saved. 
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NAME 

getlogin — get login name 

SYNOPSIS 

char ‘getlogin ( ); 

DESCRIPTION 

Getlogin returns a pointer to the login name as found in /etc/utmp. It may be 
used in conjunction with getpwnam to locate the correct password file entry 
when the same user ID is shared by several login names. 

If getlogin is called within a process that is not attached to a terminal, it 
returns a NULL pointer. The correct procedure for determining the login name 
is to call cuserid, or to call getlogin and if it fails to call getpwuid. 

FILES 

/etc/utmp 
SEE ALSO 

cuserid (3S), getgrent(3C), getpwent(3C), utmp(4). 

DIAGNOSTICS 

Returns the NULL pointer if name is not found. 

BUGS 

The return values point to static data whose content is overwritten by each call. 
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NAME 

getopt — get option letter from argument vector 
SYNOPSIS 

int getopt (argc, argv, optstring) 
int argc; 

char **argv, *opstring; 

extern char »optarg; 
extern int optind, opterr; 

DESCRIPTION 

Getopt returns the next option letter in argv that matches a letter in optstring. 
Optstring is a string of recognized option letters; if a letter is followed by a 
colon, the option is expected to have an argument that may or may not be 
separated from it by white space. Optarg is set to point to the start of the 
option argument on return from getopt. 

Getopt places in optind the argv index of the next argument to be processed. 
Because optind is external, it is normally initialized to zero automatically 
before the first call to getopt. 

When all options have been processed (i.e., up to the first non-option argu- 
ment), getopt returns EOF. The special option may be used to delimit the 

end of the options; EOF will be returned, and will be skipped. 

DIAGNOSTICS 

Getopt prints an error message on stderr and returns a question mark (?) 
when it encounters an option letter not included in optstring. This error mes- 
sage may be disabled by setting opterr to a non-zero value. 

EXAMPLE 

The following code fragment shows how one might process the arguments for a 
command that can take the mutually exclusive options a and b, and the options 
f and o, both of which require arguments: 

main (argc, argv) 
int argc; 
char **argv; 

{ 

int c; 

extern char »optarg; 
extern int optind; 


while ((c = getopt(argc, argv, "abf:o:")) != EOF) 
switch (c) { 
case 'a': 

if (bflg) 

errflg++; 

else 

aflg++; 

break; 

case 'b': 


if (aflg) 

else 

break; 


errflg++; 
bproc( ); 


case T: 


ifile = optarg; 
break; 
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case 'o': 

ofile = optarg; 
break; 

case 

errflg++; 

} 

if (errflg) { 

fprintf(stderr, "usage: 
exit (2); 

} 

for ( ; optind < argc; optind++) { 
if (access(argv[optind], 4)) { 

} 

SEE ALSO 

getopt(l) in the 3B2 Computer System User Reference Manual. 
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NAME 

getpass — read a password 
SYNOPSIS 

char ‘getpass (prompt) 
char ‘prompt; 

DESCRIPTION 

Getpass reads up to a newline or EOF from the file /dev /tty, after prompting on 
the standard error output with the null-terminated string prompt and disabling 
echoing. A pointer is returned to a null-terminated string of at most 8 charac- 
ters. If /dev/tty cannot be opened, a NULL pointer is returned. An interrupt 
will terminate input and send an interrupt signal to the calling program before 
returning. 

FILES 

/dev/tty 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of pro- 
grams not otherwise using standard I/O, more than might be expected. 

BUGS 

The return value points to static data whose content is overwritten by each call. 


10/84 


- 1 - 


10/84 



GETPW (3C) 


(C Programming Language Utilities) 


GETPW (30 


NAME 

getpw — get name from UID 

SYNOPSIS 

int getpw (uid, buf) 
int uid; 
char *buf; 

DESCRIPTION 

Getpw searches the password file for a user id number that equals uid, copies 
the line of the password file in which uid was found into the array pointed to 
by buf, and returns 0. Getpw returns non-zero if uid cannot be found. 

This routine is included only for compatibility with prior systems and should 
not be used; see getpwenti 3C) for routines to use instead. 

FILES 

/etc/passwd 
SEE ALSO 

getpwent(3C), passwd(4). 

DIAGNOSTICS 

Getpw returns non-zero on error. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase, more than 
might be expected, the size of programs not otherwise using standard I/O. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent — get password 
file entry 

SYNOPSIS 

#include <pwd.h> 

struct passwd ‘getpwent ( ) 

struct passwd ‘getpwuid (uid) 
int uid; 

struct passwd ‘getpwnam (name) 
char ‘name; 

void setpwent ( ) 
void endpwent ( ) 

struct passwd ‘fgetpwent (f) 

FILE »f; 

DESCRIPTION 

Getpwent, getpwuid and getpwnam each returns a pointer to an object with the 
following structure containing the broken-out fields of a line in the /etc/passwd 
file. Each line in the file contains a “passwd” structure, declared in the 
<pwd.h> header file: 

struct passwd { 


char 

•pwname; 

char 

»pw_passwd; 

int 

pw_uid; 

int 

pw_gid; 

char 

•pwage; 

char 

»pw_comment; 

char 

*pw_gecos; 

char 

*pw_dir; 

char 

»pw_shell; 


}; 

This structure is declared in <pwd.h> so it is not necessary to redeclare it. 

The pwcomment field is unused; the others have meanings described in 
passwd (4) . 

Getpwent when first called returns a pointer to the first passwd structure in the 
file; thereafter, it returns a pointer to the next passwd structure in the file; so 
successive calls can be used to search the entire file. Getpwuid searches from 
the beginning of the file until a numerical user id matching uid is found and 
returns a pointer to the particular structure in which it was found. Getpwnam 
searches from the beginning of the file until a login name matching name is 
found, and returns a pointer to the particular structure in which it was found. 
If an end-of-file or an error is encountered on reading, these functions return a 
NULL pointer. 

A call to setpwent has the effect of rewinding the password file to allow 
repeated searches. Endpwent may be called to close the password file when 
processing is complete. 

Fgetpwent returns a pointer to the next passwd structure in the stream /, which 
matches the format of /etc/passwd. 

FILES 

/etc/passwd 
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SEE ALSO 

getlogin(3C), getgrent(3C), passwd(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase the size of 
programs, not otherwise using standard I/O, more than might be expected. 

BUGS 

All information is contained in a static area, so it must be copied if it is to be 
saved. 
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NAME 

gets, fgets — get a string from a stream 

SYNOPSIS 

#include <stdio.h> 

char »gets (s) 
char *s; 

char »fgets (s, n, stream) 
char *s; 
int n; 

FILE «stream; 

DESCRIPTION 

Gets reads characters from the standard input stream, stdin, into the array 
pointed to by s, until a new-line character is read or an end-of-file condition is 
encountered: The new-line character is discarded and the string is terminated 
with a null character. 

Fgets reads characters from the stream into the array pointed to by s, until 
n — 1 characters are read, or a new-line character is read and transferred to s, 
or an end-of-file condition is encountered. The string is then terminated with a 
null character. 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), getc(3S), scanf(3S). 

DIAGNOSTICS 

If end-of-file is encountered and no characters have been read, no characters 
are transferred to 5 and a NULL pointer is returned. If a read error occurs, 
such as trying to use these functions on a file that has not been opened for 
reading, a NULL pointer is returned. Otherwise s is returned. 
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NAME 

getutent, getutid, getutline, pututline, setutent, endutent, utmpname — access 
utmp file entry 


SYNOPSIS 

#include <utmp.h> 

struct utmp *getutent ( ) 

struct utmp *getutid (id) 
struct utmp *id; 

struct utmp *getutline (line) 
struct utmp *line; 

void pututline (utmp) 
struct utmp *utmp; 

void setutent ( ) 
void endutent ( ) 


void utmpname (file) 
char »file; 


DESCRIPTION 


lowing type: 

struct 


tid and getutline each return a pointer to a structure of the fol- 

utmp ( 



char 

ut_user[8]; 

/* User login name */ 

char 

ut_id[4]; 

/* /etc/inittab id (usually line #) */ 

char 

ut_line[ 12]; 

/* device name (console, lnxx) */ 

short 

ut_pid; 

/» process id */ 

short 

ut_type; 

/* type of entry */ 

struct 

exit status { 


short 

etermination; 

/» Process termination status */ 

short 

e_exit; 

/* Process exit status */ 

} ut_exit; 


/* The exit status of a process 



* marked as DEAD PROCESS. */ 

timet 

ut_time; 

/* time entry was made */ 


Getutent reads in the next entry from a utmp- like file. If the file is not already 
open, it opens it. If it reaches the end of the file, it fails. 

Getutid searches forward from the current point in the utmp file until it finds 
an entry with a utjype matching id—>ut_type if the type specified is 
RUNLVL, BOOT TIME, OLD TIME or NEW TIME. If the type specified in id 
is INIT PROCESS, LOGIN_PROCESS, USER_PROCESS or DEAD_PROCESS, 
then getutid will return a pointer to the first entry whose type is one of these 
four and whose ut id field matches id — >utjd. If the end of file is reached 
without a match, it fails. 

Getutline searches forward from the current point in the utmp file until it finds 
an entry of the type LOGIN PROCESS or USER PROCESS which also has a 
utjine string matching the line — >ut line string. If the end of file is reached 
without a match, it fails. 

Pututline writes out the supplied utmp structure into the utmp file. It uses 
getutid to search forward for the proper place if it finds that it is not already at 
the proper place. It is expected that normally the user of pututline will have 
searched for the proper entry using one of the getut routines. If so, pututline 
will not search. If pututline does not find a matching slot for the new entry, it 
will add a new entry to the end of the file. 
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Setutent resets the input stream to the beginning of the file. This should be 
done before each search for a new entry if it is desired that the entire file be 
examined. 

Endutent closes the currently open file. 

Utmpname allows the user to change the name of the file examined, from 
/etc/utmp to any other file. It is most often expected that this other file will be 
/etc/wtmp. If the file does not exist, this will not be apparent until the first 
attempt to reference the file is made. Utmpname does not open the file. It just 
closes the old file if it is currently open and saves the new file name. 

FILES 

/etc/utmp 

/etc/wtmp 

SEE ALSO 

ttyslot(3C), utmp(4). 

DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for permissions or 
having reached the end of file, or upon failure to write. 

COMMENTS 

The most current entry is saved in a static structure. Multiple accesses require 
that it be copied before further accesses are made. Each call to either getutid 
or getutline sees the routine examine the static structure before performing 
more I/O. If the contents of the static structure match what it is searching for, 
it looks no further. For this reason to use getutline to search for multiple 
occurrences, it would be necessary to zero out the static after each success, or 
getutline would just return the same pointer over and over again. There is one 
exception to the rule about removing the structure before further reads are 
done. The implicit read done by pututline (if it finds that it is not already at 
the correct place in the file) will not hurt the contents of the static structure 
returned by the getutent , getutid or getutline routines, if the user has just 
modified those contents and passed the pointer back to pututline. 

These routines use buffered standard I/O for input, but pututline uses an 
unbuffered non-standard write to avoid race conditions between processes trying 
to modify the utmp and wtmp files. 
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NAME 

hsearch, hcreate, hdestroy — manage hash search tables 

SYNOPSIS 

#include <search.h> 

ENTRY *hsearch (item, action) 

ENTRY item; 

ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 

DESCRIPTION 

Hsearch is a hash-table search routine generalized from Knuth (6.4) Algorithm 
D. It returns a pointer into a hash table indicating the location at which an 
entry can be found. Item is a structure of type ENTRY (defined in the 
<search.h> header file) containing two pointers: item.key points to the com- 
parison key, and item. data points to any other data to be associated with that 
key. (Pointers to types other than character should be cast to pointer-to- 
character.) Action is a member of an enumeration type ACTION indicating the 
disposition of the entry if it cannot be found in the table. ENTER indicates that 
the item should be inserted in the table at an appropriate point. FIND indicates 
that no entry should be made. Unsuccessful resolution is indicated by the 
return of a NULL pointer. 

Hcreate allocates sufficient space for the table, and must be called before 
hsearch is used. Nel is an estimate of the maximum number of entries that 
the table will contain. This number may be adjusted upward by the algorithm 
in order to obtain certain mathematically favorable circumstances. 

Hdestroy destroys the search table, and may be followed by another call to 
hcreate. 

NOTES 

Hsearch uses open addressing with a multiplicative hash function. However, 
its source code has many other options available which the user may select by 
compiling the hsearch source with the following symbols defined to the prepro- 
cessor: 

DIV Use the remainder modulo table size as the hash function 

instead of the multiplicative algorithm. 

USCR Use a User Supplied Comparison Routine for ascertaining 
table membership. The routine should be named hcompar 
and should behave in a mannner similar to strcmp (see 
string 1 30). 

CHAINED Use a linked list to resolve collisions. If this option is 
selected, the following other options become available. 

START Place new entries at the beginning of the 

linked list (default is at the end). 

SORTUP Keep the linked list sorted by key in ascend- 
ing order. 

SORTDOWN Keep the linked list sorted by key in des- 
cending order. 

Additionally, there are preprocessor flags for obtaining debugging printout 
( — DDEBUG) and for including a test driver in the calling routine 
( — DDRIVER). The source code should be consulted for further details. 
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EXAMPLE 

The following example will read in strings followed by two numbers and store 
them in a hash table, discarding duplicates. It will then read in strings and 
find the matching entry in the hash table and print it out. 

#include <stdio.h> 

#include < search. h> 

struct info { 

int age, room; 

}; 

#define NUM EMPL 

main( ) 

{ 

/» space to store strings */ 
char string_space[NUM_EMPL‘20]; 

/* space to store employee info */ 
struct info info_space[NUM_EMPL]; 

/* next avail space in string_space */ 
char *str_ptr = string_space; 

/* next avail space in info_space */ 
struct info »info_ptr = info_space; 

ENTRY item, ‘found item, *hsearch( ); 

/* name to look for in table */ 
char name_to_find[30]; 
int i = 0; 

/* create table */ 

(void) hcreate(NUMEMPL); 

while (scanf("%s%d%d", str_ptr, &info_ptr— > age, 

&info_ptr— > room) != EOF && i++ < NUM_EMPL) { 

/* put info in structure, and structure in item */ 

item.key = str_ptr; 

item.data = (char *)info_ptr; 

str_ptr += strlen (str_ptr) + 1; 

info_ptr++; 

/* put item into table »/ 

(void) hsearch(item, ENTER); 

} 

/* access table »/ 

item.key = nametofind; 

while (scanf("%s'\ item.key) != EOF) { 

if ((foundjtem = hsearch(item, FIND)) != NULL) { 

/* if item is in the table */ 

(void) printf ("found %s, age = %d, room = %d\n", 
foundjtem— > key, 

((struct info *) found item— > data)— > age, 
((struct info *)foundjtem— >data)— >room); 

} else { 

(void) printf ("no such employee %s\n", 
name to find) 



/» this is the info stored in the table */ 

/* other than the key. */ 

5000 /* # of elements in search table */ 
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SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), malloc(3X), string(3C), tsearch(3C). 
DIAGNOSTICS 

Hsearch returns a NULL pointer if either the action is FIND and the item could 
not be found or the action is ENTER and the table is full. 

Hcreate returns zero if it cannot allocate sufficient space for the table. 
WARNING 

Hsearch and hcreate use malloci 3C) to allocate space. 

BUGS 

Only one hash search table may be active at any given time. 
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NAME 

13tol, ltol3 — convert between 3-byte integers and long integers 

SYNOPSIS 

void 13toI (lp, cp, n) 
long *lp; 
char »cp; 
int n; 

void lto!3 (cp. Ip, n) 
char *cp; 
long «lp; 
int n; 

DESCRIPTION 

L3tol converts a list of n three-byte integers packed into a character string 
pointed to by cp into a list of long integers pointed to by lp. 

Ltol3 performs the reverse conversion from long integers (lp) to three-byte 
integers (cp). 

These functions are useful for file-system maintenance where the block 
numbers are three bytes long. 

SEE ALSO 

fs (4) . 

BUGS 

Because of possible differences in byte ordering, the numerical values of the 
long integers are machine-dependent. 
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NAME 

lockf — record locking on files 
SYNOPSIS 

# include <unistd.h> 


lockf (fildes, function, size) 

long size; 

int fildes, function; 

DESCRIPTION 

The lockf command will allow sections of a file to be locked (advisory write 
locks). (Mandatory or enforcement mode record locks are not currently avail- 
able.) Locking calls from other processes which attempt to lock the locked file 
section will either return an error value or be put to sleep until the resource 
becomes unlocked. All the locks for a process are removed when the process 
terminates. (See fcntll 2) for more information about record locking.) 

Fildes is an open file descriptor. The file descriptor must have OWRONLY or 
O RDWR permission in order to establish lock with this function call. 

Function is a control value which specifies the action to be taken. The permis- 
sible values for function are defined in <unistd.h> as follows: 


#define 

#define 

#define 

#define 


FJJLOCK 0 
FLOCK 1 
F_TLOCK 2 
F TEST 3 


/* Unlock a previously locked section */ 

/* Lock a section for exclusive use »/ 

/» Test and lock a section for exclusive use */ 
/» Test section for other processes locks */ 


All other values of function are reserved for future extensions and will result in 
an error return if not implemented. 

F TEST is used to detect if a lock by another process is present on the specified 
section. F LOCK and FTLOCK both lock a section of a file if the section is 
available. F UNLOCK removes locks from a section of the file. 

Size is the number of contiguous bytes to be locked or unlocked. The resource 
to be locked starts at the current offset in the file and extends forward for a 
positive size and backward for a negative size (the preceding bytes up to but 
not including the current offset). If size is zero, the section from the current 
offset through the largest file offset is locked (i.e., from the current offset 
through the present or any future end-of-file). An area need not be allocated 
to the file in order to be locked as such locks may exist past the end-of-file. 

The sections locked with F LOCK or F TLOCK may, in whole or in part, con- 
tain or be contained by a previously locked section for the same process. When 
this occurs, or if adjacent sections occur, the sections are combined into a single 
section. If the request requires that a new element be added to the table of 
active locks and this table is already full, an error is returned, and the new sec- 
tion is not locked. 

F LOCK and F TLOCK requests differ only by the action taken if the resource 
is not available. F_LOCK will cause the calling process to sleep until the 
resource is available. F_TLOCK will cause the function to return a —1 and set 
errno to [EACCESS] error if the section is already locked by another process. 

FJJLOCK requests may, in whole or in part, release one or more locked sections 
controlled by the process. When sections are not fully released, the remaining 
sections are still locked by the process. Releasing the center section of a locked 
section requires an additional element in the table of active locks. If this table 
is full, an [EDEADLK] error is returned and the requested section is not 
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released. 

A potential for deadlock occurs if a process controlling a locked resource is put 
to sleep by accessing another process’s locked resource. Thus calls to lock or 
fcntl scan for a deadlock prior to sleeping on a locked resource. An error 
return is made if sleeping on the locked resource would cause a deadlock. 

Sleeping on a resource is interrupted with any signal. The alarmi 2) command 
may be used to provide a timeout facility in applications which require this 
facility. 

ERRORS 

The lockf utility will fail if one or more of the following are true: 

[EBADFl 

Fildes is not a valid open descriptor. 

[EACCESS] 

Cmd is FTLOCK or F TEST and the section is already locked by 
another process. 

[EDEADLK] 

Cmd is F LOCK or F TLOCK and a deadlock would occur. Also the 
cmd is either of the above or FJULOCK and the number of entries in 
the lock table would exceed the number allocated on the system. 

SEE ALSO 

close (2), creat(2), fcntl (2), intro (2), open (2), read (2), write (2). 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 

WARNINGS 

Unexpected results may occur in processes that do buffering in the user address 
space. The process may later read/write data which is/was locked. The stan- 
dard I/O package is the most common source of unexpected buffering. 
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NAME 

lsearch, lfind — linear search and update 

SYNOPSIS 

#include <stdio.h> 

#include <search.h> 

char ‘lsearch ((char »)key, (char »)base, nelp, sizeof(*key), compar) 
unsigned *nelp; 
int (‘compar) ( ); 

char *lfind ((char *)key, (char »)base, nelp, sizeof(‘key), compar) 
unsigned »nelp; 
int (*compar)( ); 

DESCRIPTION 

Lsearch is a linear search routine generalized from Knuth (6.1) Algorithm S. 
It returns a pointer into a table indicating where a datum may be found. If the 
datum does not occur, it is added at the end of the table. Key points to the 
datum to be sought in the table. Base points to the first element in the table. 
Nelp points to an integer containing the current number of elements in the 
table. The integer is incremented if the datum is added to the table. Compar 
is the name of the comparison function which the user must supply ( strcmp , for 
example). It is called with two arguments that point to the elements being 
compared. The function must return zero if the elements are equal and non- 
zero otherwise. 

Lfind is the same as lsearch except that if the datum is not found, it is not 
added to the table. Instead, a NULL pointer is returned. 

NOTES 

The pointers to the key and the element at the base of the table should be of 
type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may 
be contained in the elements in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should be 
cast into type pointer-to-element. 

EXAMPLE 

This fragment will read in < TABSIZE strings of length < ELSIZE and store 
them in a table, eliminating duplicates. 

#include <stdio.h> 

#include <search.h> 

#define TABSIZE 50 
#define ELSIZE 120 

char linefELSIZE], tab[TABSIZE][ ELSIZE], ‘lsearch( ); 
unsigned nel = 0; 
int strcmp( ); 

while (fgetsOine, ELSIZE, stdin) != NULL && 
nel < TABSIZE) 

(void) lsearch(line, (char *)tab, &nel, 

ELSIZE, strcmp); 

SEE ALSO 

bsearch(3C), hsearch(3C), tsearch(3C). 
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DIAGNOSTICS 

If the searched for datum is found, both Isearch and Ifind return a pointer to 
it. Otherwise, Ifind returns NULL and Isearch returns a pointer to the newly 
added element. 

BUGS 

Undefined results can occur if there is not enough room in the table to add a 
new item. 
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NAME 

malloc, free, realloc, calloc — main memory allocator 

SYNOPSIS 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realioc (ptr, size) 
char »ptr; 
unsigned size; 

char *caiioc (nelem, elsize) 
unsigned nelem, elsize; 

DESCRIPTION 

Malloc and free provide a simple general-purpose memory allocation package. 
Malloc returns a pointer to a block of at least size bytes suitably aligned for 
any use. 

The argument to free is a pointer to a block previously allocated by malloc, 
after free is performed this space is made available for further allocation, but 
its contents are left undisturbed. 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free. 

Malloc allocates the first big enough contiguous reach of free space found in a 
circular search from the last block allocated or freed, coalescing adjacent free 
blocks as it searches. It calls sbrk (see brk(2)) to get more memory from the 
system when there is no suitable space already free. 

Realloc changes the size of the block pointed to by ptr to size bytes and 
returns a pointer to the (possibly moved) block. The contents will be 
unchanged up to the lesser of the new and old sizes. If no free block of size 
bytes is available in the storage arena, then realloc will ask malloc to enlarge 
the arena by size bytes and will then move the data to the new space. 

Realloc also works if ptr points to a block freed since the last call of malloc, 
realloc, or calloc, thus sequences of free, malloc and realloc can exploit the 
search strategy of malloc to do storage compaction. 

Calloc allocates space for an array of nelem elements of size elsize. The space 
is initialized to zeros. 

Each of the allocation routines returns a pointer to space suitably aligned (after 
possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), malloc(3X). 

DIAGNOSTICS 

Malloc, realloc and calloc return a NULL pointer if there is no available 
memory or if the arena has been detectably corrupted by storing outside the 
bounds of a block. When this happens the block pointed to by ptr may be des- 
troyed. 

NOTES 

Search time increases when many objects have been allocated; that is, if a pro- 
gram allocates but never frees, then each successive allocation takes longer. 
For an alternate, more flexible implementation, see malloc { 3X). 
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NAME 

memccpy, memchr, memcmp, memcpy, memset — memory operations 
SYNOPSIS 

#include < memory. h> 

char amemccpy (si, s2, c, n) 
char *sl, *s2; 
int c, n; 

char *memchr (s, c, n) 
char *s; 
int c, n; 

int memcmp (si, s2, n) 
char *sl, »s2; 
int n; 

char *memcpy (si, s2, n) 
char «sl, »s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 

DESCRIPTION 

These functions operate as efficiently as possible on memory areas (arrays of 
characters bounded by a count, not terminated by a null character). They do 
not check for the overflow of any receiving memory area. 

Memccpy copies characters from memory area s2 into si, stopping after the 
first occurrence of character c has been copied, or after n characters have been 
copied, whichever comes first. It returns a pointer to the character after the 
copy of c in si, or a NULL pointer if c was not found in the first n characters 
of s2. 

Memchr returns a pointer to the first occurrence of character c in the first n 
characters of memory area s, or a NULL pointer if c does not occur. 

Memcmp compares its arguments, looking at the first n characters only, and 
returns an integer less than, equal to, or greater than 0, according as si is lexi- 
cographically less than, equal to, or greater than s2. 

Memcpy copies n characters from memory area s2 to si. It returns si. 

Memset sets the first n characters in memory area s to the value of character 
c. It returns s. 

For user convenience, all these functions are declared in the optional 
< memory. h> header file. 

BUGS 

Memcmp uses native character comparison, which is unsigned. Thus the sign 
of the value returned when one of the characters has its high-order bit set is 
implementation-dependent. 

Character movement is performed differently in different implementations. 
Thus overlapping moves may yield surprises. 
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NAME 

mktemp — make a unique file name 
SYNOPSIS 

char "mktemp (template) 
char "template; 

DESCRIPTION 

Mktemp replaces the contents of the string pointed to by template by a unique 
file name, and returns the address of template. The string in template should 
look like a file name with six trailing Xs; mktemp will replace the Xs with a 
letter and the current process ID. The letter will be chosen so that the resulting 
name does not duplicate an existing file. 

SEE ALSO 

getpid (2) , tmpfile(3S), tmpnam(3S). 

BUGS 

It is possible to run out of letters. 
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NAME 

monitor — prepare execution profile 

SYNOPSIS 

#include <mon.h> 

void monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc)( ), (*highpc)( ); 

WORD ‘buffer; 
int bufsize, nfunc; 

DESCRIPTION 

An executable program created by cc — p automatically includes calls for mon- 
itor with default parameters; monitor needn’t be called explicitly except to gain 
fine control over profiling. 

Monitor is an interface to profit (2). Lowpc and highpc are the addresses of 
two functions; buffer is the address of a (user supplied) array of bufsize 
WORDs (defined in the <mon.h> header file). Monitor arranges to record a 
histogram of periodically sampled values of the program counter, and of counts 
of calls of certain functions, in the buffer. The lowest address sampled is that 
of lowpc and the highest is just below highpc. Lowpc may not equal 0 for this 
use of monitor. At most nfunc call counts can be kept; only calls of functions 
compiled with the profiling option — p of cc( 1) are recorded. 

For the results to be significant, especially where there are small, heavily used 
routines, it is suggested that the buffer be no more than a few times smaller 
than the range of locations sampled. 

To profile the entire program, it is sufficient to use 
extern etext; 

monitor ((int (*)())2, etext, buf, bufsize, nfunc); 

Etext lies just above all the program text; see end (.30. 

To stop execution monitoring and write the results on the file mon.out, use 
monitor ((int (»)0)0, 0, 0, 0, 0); 

Prof(l) can then be used to examine the results. 

FILES 

mon.out 

/lib/libp/libc.a 

/lib/libp/libm.a 

SEE ALSO 

profil (2) , end(3C). 

cc(l) in the 3B2 Computer C Programming Language Utilities. 

prof(l) in the 3B2 Computer Extended Software Generation System Utilities. 
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NAME 

nlist — get entries from name list 

SYNOPSIS 

#include <nlist.h> 

int nlist (file-name, nl) 
char *file-name; 
struct nlist *nl; 

DESCRIPTION 

Nlist examines the name list in the executable file whose name is pointed to by 
file-name , and selectively extracts a list of values and puts them in the array of 
nlist structures pointed to by nl. The name list nl consists of an array of struc- 
tures containing names of variables, types and values. The list is terminated 
with a null name; that is, a null string is in the name position of the structure. 
Each variable name is looked up in the name list of the file. If the name is 
found, the type and value of the name are inserted in the next two fields. The 
type field will be set to 0 unless the file was compiled with the — g option. If 
the name is not found, both entries are set to 0. See a.out{ 4) for a discussion 
of the symbol table structure. 

This function is useful for examining the system name list kept in the file 
/unix. In this way programs can obtain system addresses that are up to date. 

NOTES 

The <nlist.h> header file is automatically included by <a.out.h> for compa- 
tability. However, if the only information needed from <a.out.h> is for use of 
nlist, then including <a.out.h> is discouraged. If <a.out.h> is included, the 
line “#undef n name” may need to follow it. 

SEE ALSO 

a. out (4). 

DIAGNOSTICS 

All value entries are set to 0 if the file cannot be read or if it does not contain a 
valid name list. 

Nlist returns —1 upon error; otherwise it returns 0. 
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NAME 

perror, errno, sys_errlist, sys_nerr — system error messages 

SYNOPSIS 

void perror (s) 
char *s; 

extern int errno; 
extern char *sys_errlist[ 1; 
extern int sys_nerr; 

DESCRIPTION 

Perror produces a message on the standard error output, describing the last 
error encountered during a call to a system or library function. The argument 
string s is printed first, then a colon and a blank, then the message and a new- 
line. To be of most use, the argument string should include the name of the 
program that incurred the error. The error number is taken from the external 
variable errno , which is set when errors occur but not cleared when non- 
erroneous calls are made. 

To simplify variant formatting of messages, the array of message strings 
sys_errlist is provided; errno can be used as an index in this table to get the 
message string without the new-line. Sysnerr is the largest message number 
provided for in the table; it should be checked because new error codes may be 
added to the system before they are added to the table. 

SEE ALSO 

intro (2). 
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NAME 

popen, pclose — initiate pipe to/from a process 

SYNOPSIS 

#include <stdio.h> 

FILE * popen (command, type) 
char "command, "type; 

int pclose (stream) 

FILE "stream; 

DESCRIPTION 

The arguments to popen are pointers to null-terminated strings containing, 
respectively, a shell command line and an I/O mode, either r for reading or w 
for writing. Popen creates a pipe between the calling program and the com- 
mand to be executed. The value returned is a stream pointer such that one can 
write to the standard input of the command, if the I/O mode is w, by writing to 
the file stream ; and one can read from the standard output of the command, if 
the I/O mode is r, by reading from the file stream. 

A stream opened by popen should be closed by pclose, which waits for the 
associated process to terminate and returns the exit status of the command. 

Because open files are shared, a type r command may be used as an input filter 
and a type w as an output filter. 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), system(3S). 

DIAGNOSTICS 

Popen returns a NULL pointer if files or processes cannot be created, or if the 
shell cannot be accessed. 

Pclose returns —1 if stream is not associated with a “popene d” command. 

BUGS 

If the original and “popene d” processes concurrently read or write a common 
file, neither should use buffered I/O, because the buffering gets all mixed up. 
Problems with an output filter may be forestalled by careful buffer flushing, e.g. 
with /flush', see /close (3S). 
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NAME 

printf, fprintf, sprintf — print formatted output 

SYNOPSIS 

#include <stdio.h> 

int printf (format [ , arg ] . . . ) 

char ‘format; 

int fprintf (stream, format [ , arg ] . . . ) 

FILE ‘stream; 
char ‘format; 

int sprintf (s, format [ , arg ] ... ) 

char *s, format; 

DESCRIPTION 

Printf places output on the standard output stream stdout. Fprintf places out- 
put on the named output stream. Sprintf places “output,” followed by the null 
character (\0), in consecutive bytes starting at *s; it is the user’s responsibility 
to ensure that enough storage is available. Each function returns the number 
of characters transmitted (not including the \0 in the case of sprintf), or a 
negative value if an output error was encountered. 

Each of these functions converts, formats, and prints its args under control of 
the format. The format is a character string that contains two types of 
objects: plain characters, which are simply copied to the output stream, and 
conversion specifications, each of which results in fetching of zero or more args. 
The results are undefined if there are insufficient arg s for the format. If the 
format is exhausted while args remain, the excess args are simply ignored. 

Each conversion specification is introduced by the character %. After the %, 
the following appear in sequence: 

Zero or more flags, which modify the meaning of the conversion 
specification. 

An optional decimal digit string specifying a minimum field width. If 
the converted value has fewer characters than the field width, it will be 
padded on the left (or right, if the left-adjustment flag described 
below, has been given) to the field width. If the field width for an s 
conversion is preceded by a 0, the string is right adjusted with zero- 
padding on the left. 

A precision that gives the minimum number of digits to appear for the 
d, o, u, x, or X conversions, the number of digits to appear after the 
decimal point for the e and f conversions, the maximum number of 
significant digits for the g conversion, or the maximum number of 
characters to be printed from a string in s conversion. The precision 
takes the form of a period (.) followed by a decimal digit string; a null 
digit string is treated as zero. 

An optional 1 (ell) specifying that a following d, o, u, x, or X conver- 
sion character applies to a long integer arg. A 1 before any other 
conversion character is ignored. 

A character that indicates the type of conversion to be applied. 

A field width or precision may be indicated by an asterisk (») instead of a digit 
string. In this case, an integer arg supplies the field width or precision. The 
arg that is actually converted is not fetched until the conversion letter is seen, 
so the args specifying field width or precision must appear before the arg (if 
any) to be converted. 
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The flag characters and their meanings are: 

— The result of the conversion will be left-justified within the field. 

+ The result of a signed conversion will always begin with a sign ( + 

or -). 

blank If the first character of a signed conversion is not a sign, a blank 
will be prefixed to the result. This implies that if the blank and + 
flags both appear, the blank flag will be ignored. 

# This flag specifies that the value is to be converted to an “alternate 

form.” For c, d, s, and u conversions, the flag has no effect. For o 
conversion, it increases the precision to force the first digit of the 
result to be a zero. For x or X conversion, a non-zero result will 
have Ox or OX prefixed to it. For e, E, f, g, and G conversions, the 
result will always contain a decimal point, even if no digits follow 
the point (normally, a decimal point appears in the result of these 
conversions only if a digit follows it). For g and G conversions, 
trailing zeroes will not be removed from the result (which they nor- 
mally are). 


The conversion characters and their meanings are: 

d, o,u,x,x The integer arg is converted to signed decimal, unsigned octal, 

decimal, or hexadecimal notation (x and X), respectively; the letters 
abcdef are used for x conversion and the letters ABCDEF for X 
conversion. The precision specifies the minimum number of digits 
to appear; if the value being converted can be represented in fewer 
digits, it will be expanded with leading zeroes. (For compatibility 
with older versions, padding with leading zeroes may alternatively 
be specified by prepending a zero to the field width. This does not 
imply an octal value for the field width.) The default precision is 1. 
The result of converting a zero value with a precision of zero is a 
null string. 

f The float or double arg is converted to decimal notation in the style 

“[ — Iddd.ddd,” where the number of digits after the decimal point 
is equal to the precision specification. If the precision is missing, six 
digits are output; if the precision is explicitly 0, no decimal point 
appears. 

e, E The float or double arg is converted in the style “[ — ]d.ddde±dd,” 

where there is one digit before the decimal point and the number of 
digits after it is equal to the precision; when the precision is miss- 
ing, six digits are produced; if the precision is zero, no decimal point 
appears. The E format code will produce a number with E instead 
of e introducing the exponent. The exponent always contains at 
least two digits. 

g,G The float or double arg is printed in style f or e (or in style E in the 

case of a G format code), with the precision specifying the number 
of significant digits. The style used depends on the value converted: 
style e will be used only if the exponent resulting from the conver- 
sion is less than —4 or greater than the precision. Trailing zeroes 
are removed from the result; a decimal point appears only if it is 
followed by a digit. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) and characters 

from the string are printed until a null character (\0) is encoun- 
tered or the number of characters indicated by the precision 
specification is reached. If the precision is missing, it is taken to be 
infinite, so all characters up to the first null character are printed. 
A NULL value for arg will yield undefined results. 
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% Print a % ; no argument is converted. 

In no case does a non-existent or small field width cause truncation of a field; if 
the result of a conversion is wider than the field width, the field is simply 
expanded to contain the conversion result. Characters generated by printf and 
fprintf are printed as if putcdS) had been called. 

EXAMPLES 

To print a date and time in the form “Sunday, July 3, 10:02,” where weekday 
and month are pointers to null-terminated strings: 

printf ("%s, %s %d, %d:%.2d", weekday, month, day, hour, min); 

To print ir to 5 decimal places: 

printf ("pi = %.5f", 4 * atan(l.O)); 

SEE ALSO 

ecvt(3C), putc(3S), scanf(3S), stdio(3S). 
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NAME 

putc, putchar, fputc, putw — put character or word on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 
int c; 

FILE ‘stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 
int c; 

FILE ‘stream; 

int putw (w, stream) 
int w; 

FILE ‘stream; 

DESCRIPTION 

Putc writes the character c onto the output stream (at the position where the 
file pointer, if defined, is pointing). Putchar(c) is defined as putcic, stdout) . 
Putc and putchar are macros. 

Fputc behaves like putc , but is a function rather than a macro. Fputc runs 
more slowly than putc , but it takes less space per invocation and its name can 
be passed as an argument to a function. 

Putw writes the word (i.e. integer) w to the output stream (at the position at 
which the file pointer, if defined, is pointing). The size of a word is the size of 
an integer and varies from machine to machine. Putw neither assumes nor 
causes special alignment in the file. 

Output streams, with the exception of the standard error stream stderr, are by 
default buffered if the output refers to a file and line-buffered if the output 
refers to a terminal. The standard error output stream stderr is by default 
unbuffered, but use of freopen (see fopeni, 3S)) will cause it to become buffered 
or line-buffered. When an output stream is unbuffered, information is queued 
for writing on the destination file or terminal as soon as written; when it is 
buffered, many characters are saved up and written as a block. When it is 
line-buffered, each line of output is queued for writing on the destination termi- 
nal as soon as the line is completed (that is, as soon as a new-line character is 
written or terminal input is requested). SetbufOS ) or Setbufi 3S) may be used 
to change the stream’s buffering strategy. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). 
DIAGNOSTICS 

On success, these functions each return the value they have written. On 
failure, they return the constant EOF. This will occur if the file stream is not 
open for writing or if the output file cannot be grown. Because EOF is a valid 
integer, /error (3S) should be used to detect putw errors. 

BUGS 

Because it is implemented as a macro, putc treats incorrectly a stream argu- 
ment with side effects. In particular, putc(c, *f++); doesn’t work sensibly. 
Fputc should be used instead. 

Because of possible differences in word length and byte ordering, files written 
using putw are machine-dependent, and may not be read using getw on a 
different processor. 
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NAME 

putenv — change or add value to environment 

SYNOPSIS 

int putenv (string) 
char ‘string; 

DESCRIPTION 

String points to a string of the form "name=value.” Putenv makes the value 
of the environment variable name equal to value by altering an existing vari- 
able or creating a new one. In either case, the string pointed to by string 
becomes part of the environment, so altering the string will change the environ- 
ment. The space used by string is no longer used once a new string-defining 
name is passed to putenv. 

SEE ALSO 

exec(2), getenv(3C), malloc(3C), environ(5). 

DIAGNOSTICS 

Putenv returns non-zero if it was unable to obtain enough space via malloc for 
an expanded environment, otherwise zero. 

WARNINGS 

Putenv manipulates the environment pointed to by environ, and can be used in 
conjunction with getenv. However, envp (the third argument to main) is not 
changed. 

This routine uses malloc {1C) to enlarge the environment. 

After putenv is called, environmental variables are not in alphabetical order. 

A potential error is to call putenv with an automatic variable as the argument, 
then exit the calling function while string is still part of the environment. 
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NAME 

putpwent — write password file entry 

SYNOPSIS 

#include <pwd.h> 

int putpwent (p, f) 
struct passwd «p; 

FILE *f; 

DESCRIPTION 

Putpwent is the inverse of getpwent (3C). Given a pointer to a passwd struc- 
ture created by getpwent (or getpwuid or getpwnam ) , putpwent writes a line on 
the stream /, which matches the format of /etc/passwd. 

SEE ALSO 

getpwent (3C). 

DIAGNOSTICS 

Putpwent returns non-zero if an error was detected during its operation, other- 
wise zero. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of pro- 
grams, not otherwise using standard I/O, more than might be expected. 
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NAME 

puts, fputs — put a string on a stream 

SYNOPSIS 

#include <stdio.h> 

int puts (s) 
char *s; 

int fputs (s, stream) 
char »s; 

FILE »stream; 

DESCRIPTION 

Puts writes the null-terminated string pointed to by s, followed by a new-line 
character, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by s to the named output 
stream . 

Neither function writes the terminating null character. 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putc(3S). 

DIAGNOSTICS 

Both routines return EOF on error. This will happen if the routines try to write 
on a file that has not been opened for writing. 

NOTES 

Puts appends a new-line character while fputs does not. 
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NAME 

qsort — quicker sort 
SYNOPSIS 

void qsort ((char *) base, nel, sizeof (*base), compar) 

unsigned nel; 

int (»compar)( ); 

DESCRIPTION 

Qsort is an implementation of the quicker-sort algorithm. It sorts a table of 
data in place. 

Base points to the element at the base of the table. Nel is the number of ele- 
ments in the table. Compar is the name of the comparison function, which is 
called with two arguments that point to the elements being compared. As the 
function must return an integer less than, equal to, or greater than zero, so 
must the first argument to be considered be less than, equal to, or greater than 
the second. 

NOTES 

The pointer to the base of the table should be of type pointer-to-element, and 
cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may 
be contained in the elements in addition to the values being compared. 

The order in the output of two items which compare as equal is unpredictable. 

SEE ALSO 

bsearch(3C), lsearch(3C), string(3C). 

sort(l) in the 3B2 Computer System User Reference Manual. 
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NAME 

rand, srand - simple random-number generator 

SYNOPSIS 

int rand ( ) 

void srand (seed) 
unsigned seed; 

DESCRIPTION 

Rand uses a multiplicative congruential random-number generator with period 
2 that returns successive pseudo-random numbers in the range from 0 to 
2 15 — 1 . 

Srand can be called at any time to reset the random-number generator to a 
random starting point. The generator is initially seeded with a value of 1 . 

NOTES 

The spectral properties of rand leave a great deal to be desired. Drand48( 3C) 
provides a much better, though more elaborate, random-number generator. 

SEE ALSO 

drand48(3C). 
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NAME 

scanf, fscanf, sscanf — convert formatted input 

SYNOPSIS 

#include <stdio.h> 

int scanf (format t , pointer ] . . . ) 

char ‘format; 

int fscanf (stream, format [ , pointer ] . . . ) 

FILE ‘stream; 
char ‘format; 

int sscanf (s, format [ , pointer ] ... ) 

char *s, ‘format; 

DESCRIPTION 

Scanf reads from the standard input stream stdin. Fscanf reads from the 
named input stream. Sscanf reads from the character string s. Each function 
reads characters, interprets them according to a format, and stores the results 
in its arguments. Each expects, as arguments, a control string format 
described below, and a set of pointer arguments indicating where the converted 
input should be stored. 

The control string usually contains conversion specifications, which are used to 
direct interpretation of input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) which, 
except in two cases described below, cause input to be read up to the next 
non-white-space character. 

2. An ordinary character (not %), which must match the next character of 
the input stream. 

3. Conversion specifications, consisting of the character %, an optional assign- 
ment suppressing character », an optional numerical maximum field width, 
an optional I (ell) or h indicating the size of the receiving variable, and a 
conversion code. 

A conversion specification directs the conversion of the next input field; the 
result is placed in the variable pointed to by the corresponding argument, unless 
assignment suppression was indicated by *. The suppression of assignment pro- 
vides a way of describing an input field which is to be skipped. An input field 
is defined as a string of non-space characters; it extends to the next inappropri- 
ate character or until the field width, if specified, is exhausted. For all descrip- 
tors except “[” and “c”, white space leading an input field is ignored. 

The conversion code indicates the interpretation of the input field; the 
corresponding pointer argument must usually be of a restricted type. For a 
suppressed field, no pointer argument is given. The following conversion codes 
are legal; 

% a single % is expected in the input at this point; no assignment is done, 

d a decimal integer is expected; the corresponding argument should be an 

integer pointer. 

u an unsigned decimal integer is expected; the corresponding argument 

should be an unsigned integer pointer. 

o an octal integer is expected; the corresponding argument should be an 

integer pointer. 
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x a hexadecimal integer is expected; the corresponding argument should 
be an integer pointer. 

e,f,g a floating point number is expected; the next field is converted accord- 
ingly and stored through the corresponding argument, which should be 
a pointer to a float. The input format for floating point numbers is an 
optionally signed string of digits, possibly containing a decimal point, 
followed by an optional exponent field consisting of an E or an e, fol- 
lowed by an optional +, — , or space, followed by an integer, 
s a character string is expected; the corresponding argument should be a 

character pointer pointing to an array of characters large enough to 
accept the string and a terminating \0, which will be added automati- 
cally. The input field is terminated by a white-space character, 
c a character is expected; the corresponding argument should be a char- 

acter pointer. The normal skip over white space is suppressed in this 
case; to read the next non-space character, use % Is. If a field width is 
given, the corresponding argument should refer to a character array; 
the indicated number of characters is read. 

[ indicates string data and the normal skip over leading white space is 

suppressed. The left bracket is followed by a set of characters, which 
we will call the scanset, and a right bracket; the input field is the max- 
imal sequence of input characters consisting entirely of characters in 
the scanset. The circumflex ('), when it appears as the first character 
in the scanset, serves as a complement operator and redefines the scan- 
set as the set of all characters not contained in the remainder of the 
scanset string. There are some conventions used in the construction of 
the scanset. A range of characters may be represented by the con- 
struct first— last, thus [0123456789] may be expressed [0—9]. Using 
this convention, first must be lexically less than or equal to last, or else 
the dash will stand for itself. The dash will also stand for itself when- 
ever it is the first or the last character in the scanset. To include the 
right square bracket as an element of the scanset, it must appear as the 
first character (possibly preceded by a circumflex) of the scanset, and 
in this case it will not be syntactically interpreted as the closing 
bracket. The corresponding argument must point to a character array 
large enough to hold the data field and the terminating \0, which will 
be added automatically. At least one character must match for this 
conversion to be considered successful. 

The conversion characters d, u, o, and x may be preceded by 1 or h to indicate 
that a pointer to long or to short rather than to int is in the argument list. 
Similarly, the conversion characters e, f, and g may be preceded by 1 to indicate 
that a pointer to double rather than to float is in the argument list. The 1 or h 
modifier is ignored for other conversion characters. 

Scan f conversion terminates at EOF, at the end of the control string, or when 
an input character conflicts with the control string. In the latter case, the 
offending character is left unread in the input stream. 

Scan f returns the number of successfully matched and assigned input items; 
this number can be zero in the event of an early conflict between an input char- 
acter and the control string. If the input ends before the first conflict or 
conversion, EOF is returned. 
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EXAMPLES 

The call: 

int i, n; float x; char name[50]; 
n = scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E— 1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and name 
will contain thompson\0. Or: 

int i; float x; char name[50]; 

(void) scant (”%2d%f%*d %[0— 9]", &i, &x, name); 
with input: 

56789 0123 56a72 

will assign 56 to /, 789.0 to x, skip 0123, and place the string 56\0 in name. 
The next call to getchar (see getci. 3S)) will return a. 

SEE ALSO 

getc(3S), printf(3S), strtod(3C), strtol(3C). 

DIAGNOSTICS 

These functions return EOF on end of input and a short count for missing or 
illegal data items. 

BUGS 

The success of literal matches and suppressed assignments is not directly deter- 
minable. 

Trailing white space (including a new-line) is left unread unless matched in the 
control string. 
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NAME 

setbuf, setvbuf — assign buffering to a stream 

SYNOPSIS 

#include <stdio.h> 

void setbuf (stream, buf) 

FILE ‘stream; 
char »buf; 

int setvbuf (stream, buf, type, size) 

FILE ‘stream; 
char ‘buf; 
int type, size; 

DESCRIPTION 

Setbuf may be used after a stream has been opened but before it is read or 
written. It causes the array pointed to by buf to be used instead of an 
automatically allocated buffer. If buf is the NULL pointer input/output will be 
completely unbuffered. 

A constant BUFSIZ, defined in the <stdio.h> header file, tells how big an 
array is needed: 

char buf[BUFSIZ]; 

Setvbuf may be used after a stream has been opened but before it is read or 
written. Type determines how stream will be buffered. Legal values for type 
(defined in stdio.h) are: 

10FBF causes input/output to be fully buffered. 

IOLBF causes output to be line buffered; the buffer will be flushed 

when a newline is written, the buffer is full, or input is 
requested. 

JONBF causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used for buffering, 
instead of an automatically allocated buffer. Size specifies the size of the 
buffer to be used. The constant BUFSIZ in <stdio.h> is suggested as a good 
buffer size. If input/output is unbuffered, buf and size are ignored. 

By default, output to a terminal is line buffered and all other input/output is 
fully buffered. 

SEE ALSO 

fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 

DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a non-zero value. 
Otherwise, the value returned will be zero. 

NOTES 

A common source of error is allocating buffer space as an “automatic” variable 
in a code block, and then failing to close the stream in the same block. 
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NAME 

setjmp, longjmp — non-local goto 

SYNOPSIS 

#include <setjmp.h> 

int setjmp (env) 
jmp_buf env; 

void longjmp (env, val) 
jmp_buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and interrupts encountered in 
a low-level subroutine of a program. 

Setjmp saves its stack environment in env (whose type, jmp_buf, is defined in 
the <setjmp.h> header file) for later use by longjmp. It returns the value 0. 

Longjmp restores the environment saved by the last call of setjmp with the 
corresponding env argument. After longjmp is completed, program execution 
continues as if the corresponding call of setjmp (which must not itself have 
returned in the interim) had just returned the value val. Longjmp cannot 
cause setjmp to return the value 0. If longjmp is invoked with a second argu- 
ment of 0, setjmp will return 1. All accessible data had values as of the time 
longjmp was called. 

SEE ALSO 

signal (2). 

WARNING 

If longjmp is called even though env was never primed by a call to setjmp, or 
when the last such call was in a function which has since returned, absolute 
chaos is guaranteed. 
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NAME 

sleep — suspend execution for interval 
SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 

DESCRIPTION 

The current process is suspended from execution for the number of seconds 
specified by the argument. The actual suspension time may be less than that 
requested for two reasons: (1) Because scheduled wakeups occur at fixed 1- 
second intervals, (on the second, according to an internal clock) and (2) 
because any caught signal will terminate the sleep following execution of that 
signal’s catching routine. Also, the suspension time may be longer than 
requested by an arbitrary amount due to the scheduling of other activity in the 
system. The value returned by sleep will be the “unslept” amount (the 
requested time minus the time actually slept) in case the caller had an alarm 
set to go off earlier than the end of the requested sleep time, or premature 
arousal due to another caught signal. 

The routine is implemented by setting an alarm signal and pausing until it (or 
some other signal) occurs. The previous state of the alarm signal is saved and 
restored. The calling program may have set up an alarm signal before calling 
sleep. If the sleep time exceeds the time till such alarm signal, the process 
sleeps only until the alarm signal would have occurred. The caller’s alarm 
catch routine is executed just before the sleep routine returns. But if the sleep 
time is less than the time till such alarm, the prior alarm time is reset to go off 
at the same time it would have without the intervening sleep. 

SEE ALSO 

alarm (2), pause (2), signal (2). 
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NAME 

ssignal, gsignal — software signals 

SYNOPSIS 

#include <signal.h> 

int ('■ssignal (sig, action) )( ) 
int sig, (*action)( ); 

int gsignal (sig) 
int sig; 

DESCRIPTION 

Ssignal and gsignal implement a software facility similar to signal (2). This 
facility is used by the Standard C Library to enable users to indicate the dispo- 
sition of error conditions, and is also made available to users for their own pur- 
poses. 

Software signals made available to users are associated with integers in the 
inclusive range 1 through 15. A call to ssignal associates a procedure, action, 
with the software signal sig; the software signal, sig, is raised by a call to gsig- 
nal. Raising a software signal causes the action established for that signal to 
be taken. 

The first argument to ssignal is a number identifying the type of signal for 
which an action is to be established. The second argument defines the action; it 
is either the name of a (user-defined) action function or one of the manifest 
constants SIG_DFL (default) or SIG_IGN (ignore). Ssignal returns the action 
previously established for that signal type; if no action has been established or 
the signal number is illegal, ssignal returns SIG_DFL. 

Gsignal raises the signal identified by its argument, sig; 

If an action function has been established for sig, then that action is reset 
to SIG_DFL and the action function is entered with argument sig. Gsig- 
nal returns the value returned to it by the action function. 

If the action for sig is SIG_IGN, gsignal returns the value 1 and takes no 
other action. 

If the action for sig is SIG DFL, gsignal returns the value 0 and takes no 
other action. 

If sig has an illegal value or no action was ever specified for sig, gsignal 
returns the value 0 and takes no other action. 

SEE ALSO 

signal (2) . 

NOTES 

There are some additional signals with numbers outside the range 1 through 15 
which are used by the Standard C Library to indicate error conditions. Thus, 
some signal numbers outside the range 1 through 15 are legal, although their 
use may interfere with the operation of the Standard C Library. 
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NAME 

stdio — standard buffered input/output package 

SYNOPSIS 

#include <stdio.h> 

FILE *stdin, *stdout, *stderr; 

DESCRIPTION 

The functions described in the entries of sub-class 3S of this manual constitute 
an efficient, user-level I/O buffering scheme. The in-line macros geic(3S) and 
putci 3S) handle characters quickly. The macros getchar and putchar, and the 
higher-level routines fgetc, /gets, fprintf, fputc, fputs, fread, fscanf, f write , 
gets , getw, print f, puts, putw, and scan/ all use or act as if they use getc and 
putc\ they can be freely intermixed. 

A file with associated buffering is called a stream and is declared to be a 
pointer to a defined type FILE. Fopen (3S) creates certain descriptive data for a 
stream and returns a pointer to designate the stream in all further transactions. 
Normally, there are three open streams with constant pointers declared in the 
< stdio. h> header file and associated with the standard open files: 

stdin standard input file 

stdout standard output file 

stderr standard error file 

A constant NULL (0) designates a nonexistent pointer. 

An integer-constant EOF (—1) is returned upon end-of-file or error by most 
integer functions that deal with streams (see the individual descriptions for 
details). 

An integer constant BUFSIZ specifies the size of the buffers used by the partic- 
ular implementation. 

Any program that uses this package must include the header file of pertinent 
macro definitions, as follows: 

#include <stdio.h> 

The functions and constants mentioned in the entries of sub-class 3S of this 
manual are declared in that header file and need no further declaration. The 
constants and the following “functions” are implemented as macros (redeclara- 
tion of these names is perilous): getc, getchar, putc, putchar, /error, feof, 
clearerr, and fileno. 

SEE ALSO 

open(2), close(2), lseek(2), pipe(2), read(2), write(2), ctermid(3S), 
cuserid(3S), fclose(3S), ferror(3S), fopen(3S), fread(3S), fseek(3S), getc(3S), 
gets(3S), popen(3S), printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), 
system(3S), tmpfile(3S), tmpnam(3S), ungetc(3S). 

DIAGNOSTICS 

Invalid stream pointers will usually cause grave disorder, possibly including 
program termination. Individual function descriptions describe the possible 
error conditions. 
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NAME 

ftok — standard interprocess communication package 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

key_t ftok (path, id) 
char *path; 
char id; 

DESCRIPTION 

All interprocess communication facilities require the user to supply a key to be 
used by the msgget (.2), semget (2) , and shmget (2) system calls to obtain inter- 
process communication identifiers. One suggested method for forming a key is 
to use the ftok subroutine described below. Another way to compose keys is to 
include the project ID in the most significant byte and to use the remaining 
portion as a sequence number. There are many other ways to form keys, but it 
is necessary for each system to define standards for forming them. If some 
standard is not adhered to, it will be possible for unrelated processes to uninten- 
tionally interfere with each other’s operation. Therefore, it is strongly sug- 
gested that the most significant byte of a key in some sense refer to a project so 
that keys do not conflict across a given system. 

Ftok returns a key based on path and id that is usable in subsequent msgget, 
semget, and shmget system calls. Path must be the path name of an existing 
file that is accessible to the process. Id is a character which uniquely identifies 
a project. Note that ftok will return the same key for linked files when called 
with the same id and that it will return different keys when called with the 
same file name but different ids. 

SEE ALSO 

intro (2), msgget (2), semget (2), shmget (2). 

DIAGNOSTICS 

Ftok returns (key_t) —1 if path does not exist or if it is not accessible to the 
process. 

WARNING 

If the file whose path is passed to ftok is removed when keys still refer to the 
file, future calls to ftok with the same path and id will return an error. If the 
same file is recreated, then ftok is likely to return a different key than it did 
the original time it was called. 
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NAME 

strcat, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, strrchr, strpbrk, 
strspn, strcspn, strtok — string operations 

SYNOPSIS 

#include <string.h> 

char *strcat (si, s2) 
char *sl, »s2; 

char *stmcat (si, s2, n) 
char *sl, ‘s2; 
int n; 

int strcmp (si, s2) 
char *sl, »s2; 

int strncmp (si, s2, n) 
char »sl, *s2; 
int n; 

char *strcpy (si, s2) 
char «sl, *s2; 

char ‘strncpy (si, s2, n) 
char »sl, »s2; 
int n; 

int strlen (s) 
char »s; 

char ‘strchr (s, c) 
char »s; 
int c; 

char ‘strrchr (s, c) 
char »s; 
int c; 

char ‘Strpbrk (si, s2) 
char »sl, ‘s2; 

int strspn (si, s2) 
char *sl, «s2; 

int strcspn (si, s2) 
char *sl, »s2; 

char ‘strtok (si, s2) 
char »sl, »s2; 

DESCRIPTION 

The arguments si, s2 and s point to strings (arrays of characters terminated by 
a null character). The functions strcat , strncat , strcpy, and strncpy all alter 
si. These functions do not check for overflow of the array pointed to by si. 

Strcat appends a copy of string s2 to the end of string si. Strncat appends at 
most n characters. Each returns a pointer to the null-terminated result. 

Strcmp compares its arguments and returns an integer less than, equal to, or 
greater than 0, according as si is lexicographically less than, equal to, or 
greater than s2. Strncmp makes the same comparison but looks at at most n 
characters. 
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Strcpy copies string s2 to si, stopping after the null character has been copied. 
Strncpy copies exactly n characters, truncating s2 or adding null characters to 
si if necessary. The result will not be null-terminated if the length of s2 is n 
or more. Each function returns si. 

Strlen returns the number of characters in s, not including the terminating null 
character. 

Strchr ( strrchr ) returns a pointer to the first (last) occurrence of character c in 
string s, or a NULL pointer if c does not occur in the string. The null charac- 
ter terminating a string is considered to be part of the string. 

Strpbrk returns a pointer to the first occurrence in string si of any character 
from string s2, or a NULL pointer if no character from s2 exists in si. 

Strspn ( strcspn ) returns the length of the initial segment of string si which 
consists entirely of characters from (not from) string s2. 

Strtok considers the string si to consist of a sequence of zero or more text 
tokens separated by spans of one or more characters from the separator string 
s2. The first call (with pointer si specified) returns a pointer to the first char- 
acter of the first token, and will have written a null character into si immedi- 
ately following the returned token. The function keeps track of its position in 
the string between separate calls, so that subsequent calls (which must be made 
with the first argument a NULL pointer) will work through the string si 
immediately following that token. In this way subsequent calls will work 
through the string si until no tokens remain. The separator string s2 may be 
different from call to call. When no token remains in si, a NULL pointer is 
returned. 

For user convenience, all these functions are declared in the optional 
<string.h> header file. 

BUGS 

Strcmp and strncmp use native character comparison, which is unsigned. Thus 
the sign of the value returned when one of the characters has its high-order bit 
set is implementation-dependent. 

Character movement is performed differently in different implementations. 
Thus overlapping moves may yield surprises. 
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NAME 

strtod, atof — convert string to double-precision number 
SYNOPSIS 

double strtod (str, ptr) 
char *str, **ptr; 

double atof (str) 
char *str; 

DESCRIPTION 

Strtod returns as a double-precision floating-point number the value 
represented by the character string pointed to by str. The string is scanned up 
to the first unrecognized character. 

Strtod recognizes an optional string of “white-space” characters (as defined by 
isspace in ctypei. 3C)), then an optional sign, then a string of digits optionally 
containing a decimal point, then an optional e or E followed by an optional sign 
or space, followed by an integer. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating 
the scan is returned in the location pointed to by ptr. If no number can be 
formed, *ptr is set to str , and zero is returned. 

Atof (str) is equivalent to strtod (str, (char **)NULL). 

SEE ALSO 

ctype(3C), scanf(3S), strtol(3C). 

DIAGNOSTICS 

If the correct value would cause overflow, ±HUGE is returned (according to the 
sign of the value), and errno is set to ERANGE. 

If the correct value would cause underflow, zero is returned and errno is set to 
ERANGE. 
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NAME 

strtol, atol, atoi — convert string to integer 
SYNOPSIS 

long strtol (str, ptr, base) 
char *str, »®ptr; 
int base; 

long atol (str) 
char *str; 

int atoi (str) 
char *str; 

DESCRIPTION 

Strtol returns as a long integer the value represented by the character string 
pointed to by str. The string is scanned up to the first character inconsistent 
with the base. Leading “white-space” characters (as defined by isspace in 
ctypei 30) are ignored. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating 
the scan is returned in the location pointed to by ptr. If no integer can be 
formed, that location is set to str , and zero is returned. 

If base is positive (and not greater than 36), it is used as the base for conver- 
sion. After an optional leading sign, leading zeros are ignored, and “Ox” or 
“OX” is ignored if base is 16. 

If base is zero, the string itself determines the base thusly: After an optional 
leading sign a leading zero indicates octal conversion, and a leading “Ox” or 
“OX” hexadecimal conversion. Otherwise, decimal conversion is used. 

Truncation from long to int can, of course, take place upon assignment or by an 
explicit cast. 

Atol(str) is equivalent to strtol (str, (char **)NULL, 10). 

Atoi (str) is equivalent to (int) strtol (str, (char **)NULL, 10). 

SEE ALSO 

ctype(3C), scanf(3S), strtod(3C). 

BUGS 

Overflow conditions are ignored. 
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NAME 

swab — swap bytes 
SYNOPSIS 

void swab (from, to, nbytes) 
char *from, *to; 
int nbytes; 

DESCRIPTION 

Swab copies nbytes bytes pointed to by from to the array pointed to by to, 
exchanging adjacent even and odd bytes. It is useful for carrying binary data 
between PDP-lls and other machines. Nbytes should be even and non- 
negative. If nbytes is odd and positive swab uses nbytes — 1 instead. If nbytes is 
negative, swab does nothing. 
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NAME 

system — issue a shell command 

SYNOPSIS 

#include <stdio.h> 

int system (string) 
char *string; 

DESCRIPTION 

System causes the string to be given to sh( 1) as input, as if the string had 
been typed as a command at a terminal. The current process waits until the 
shell has completed, then returns the exit status of the shell. 

FILES 

/bin/sh 

SEE ALSO 

exec (2). 

sh(l) in the 3B2 Computer System User Reference Manual. 

DIAGNOSTICS 

System forks to create a child process that in turn exec’s /bin/sh in order to 
execute string. If the fork or exec fails, system returns a negative value and 
sets errno. 
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NAME 

tmpfile — create a temporary file 

SYNOPSIS 

#include <stdio.h> 

FILE * tmpfile 0 
DESCRIPTION 

Tmpfile creates a temporary file using a name generated by tmpnami. 3S), and 
returns a corresponding FILE pointer. If the file cannot be opened, an error 
message is printed using perrori. 3C), and a NULL pointer is returned. The file 
will automatically be deleted when the process using it terminates. The file is 
opened for update ("w+"). 

SEE ALSO 

creat(2), unlink (2), fopen(3S), mktemp(3C), perror(3C), tmpnam(3S). 
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NAME 

tmpnam, tempnam — create a name for a temporary file 

SYNOPSIS 

#include <stdio.h> 

char *tmpnam (s) 
char *s; 

char »tempnam (dir, pfx) 
char *dir, *pfx; 

DESCRIPTION 

These functions generate file names that can safely be used for a temporary 
file. 

Tmpnam always generates a file name using the path-prefix defined as 
P tmpdir in the <stdio.h> header file. If s is NULL, tmpnam leaves its result 
in an internal static area and returns a pointer to that area. The next call to 
tmpnam will destroy the contents of the area. If 5 is not NULL, it is assumed 
to be the address of an array of at least Ltmpnam bytes, where Ltmpnam is a 
constant defined in <stdio.h>\ tmpnam places its result in that array and 
returns s. 

Tempnam allows the user to control the choice of a directory. The argument 
dir points to the name of the directory in which the file is to be created. If dir 
is NULL or points to a string which is not a name for an appropriate directory, 
the path-prefix defined as P_tmpdir in the <stdio.h> header file is used. If 
that directory is not accessible, /tmp will be used as a last resort. This entire 
sequence can be up-staged by providing an environment variable TMPDIR in 
the user’s environment, whose value is the name of the desired temporary-file 
directory. 

Many applications prefer their temporary files to have certain favorite initial 
letter sequences in their names. Use the pfx argument for this. This argument 
may be NULL or point to a string of up to five characters to be used as the first 
few characters of the temporary-file name. 

Tempnam uses mallocl 3C) to get space for the constructed file name, and 
returns a pointer to this area. Thus, any pointer value returned from tempnam 
may serve as an argument to free (see malloci 30). If tempnam cannot 
return the expected result for any reason, i.e. malloc(. 3C) failed, or none of 
the above mentioned attempts to find an appropriate directory was successful, a 
NULL pointer will be returned. 

NOTES 

These functions generate a different file name each time they are called. 

Files created using these functions and either fopeni 3S) or creati, 2) are tem- 
porary only in the sense that they reside in a directory intended for temporary 
use, and their names are unique. It is the user’s responsibility to use unlink (2) 
to remove the file when its use is ended. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), mktemp(3C), tmpfile(3S). 

BUGS 

If called more than 17,576 times in a single process, these functions will start 
recycling previously used names. 

Between the time a file name is created and the file is opened, it is possible for 
some other process to create a file with the same name. This can never happen 
if that other process is using these functions or mktemp, and the file names are 
chosen so as to render duplication by other means unlikely. 
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NAME 

tsearch, tfind, tdelete, twalk — manage binary search trees 

SYNOPSIS 

#include <search.h> 

char «tsearch ((char *) key, (char «*) rootp, compar) 
int (»compar)( ); 

char *tfind ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char »tdelete ((char *) key, (char »*) rootp, compar) 
int (*compar)( ); 

void twalk ((char ») root, action) 
void (‘action) ( ); 

DESCRIPTION 

Tsearch, tfind, tdelete, and twalk are routines for manipulating binary search 
trees. They are generalized from Knuth (6.2.2) Algorithms T and D. All com- 
parisons are done with a user-supplied routine. This routine is called with two 
arguments, the pointers to the elements being compared. It returns an integer 
less than, equal to, or greater than 0, according to whether the first argument is 
to be considered less than, equal to or greater than the second argument. The 
comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

Tsearch is used to build and access the tree. Key is a pointer to a datum to be 
accessed or stored. If there is a datum in the tree equal to *key (the value 
pointed to by key), a pointer to this found datum is returned. Otherwise, *key 
is inserted, and a pointer to it returned. Only pointers are copied, so the calling 
routine must store the data. Rootp points to a variable that points to the root 
of the tree. A NULL value for the variable pointed to by rootp denotes an 
empty tree; in this case, the variable will be set to point to the datum which 
will be at the root of the new tree. 

Like tsearch, tfind will search for a datum in the tree, returning a pointer to it 
if found. However, if it is not found, tfind will return a NULL pointer. The 
arguments for tfind are the same as for tsearch. 

Tdelete deletes a node from a binary search tree. The arguments are the same 
as for tsearch. The variable pointed to by rootp will be changed if the deleted 
node was the root of the tree. Tdelete returns a pointer to the parent of the 
deleted node, or a NULL pointer if the node is not found. 

Twalk traverses a binary search tree. Root is the root of the tree to be 
traversed. (Any node in a tree may be used as the root for a walk below that 
node.) Action is the name of a routine to be invoked at each node. This rou- 
tine is, in turn, called with three arguments. The first argument is the address 
of the node being visited. The second argument is a value from an enumeration 
data type typedef enum { preorder, postorder, endorder, leaf } VISIT; (defined 
in the <search.h> header file), depending on whether this is the first, second 
or third time that the node has been visited (during a depth-first, left-to-right 
traversal of the tree), or whether the node is a leaf. The third argument is the 
level of the node in the tree, with the root being level zero. 

The pointers to the key and the root of the tree should be of type pointer-to- 
element, and cast to type pointer-to-character. Similarly, although declared as 
type pointer-to-character, the value returned should be cast into type pointer- 
to-element. 
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EXAMPLE 

The following code reads in strings and stores structures containing a pointer to 
each string and a count of its length. It then walks the tree, printing out the 
stored strings and their lengths in alphabetical order. 

#include < search. h> 

#include <stdio.h> 

struct node { /* pointers to these are stored in the tree */ 

char ‘string; 
int length; 

}; 

char string_space[ 10000]; /* space to store strings */ 

struct node nodes[500]; /* nodes to store */ 

struct node »root = NULL; /* this points to the root */ 

main( ) 

{ 

char *strptr = stringspace; 
struct node ‘nodeptr = nodes; 
void print_node( ), twalkf ); 
int i = 0, node_compare( ); 

while (gets (strptr) != NULL && i++ < 500) { 

/» set node »/ 

nodeptr— > string = strptr; 

nodeptr— > length = strlen (strptr); 

/* put node into the tree */ 

(void) tsearch((char *) nodeptr, &root, 
node_compare); 

/* adjust pointers, so we don’t overwrite tree */ 
strptr += nodeptr— > length + 1; 
nodeptr++; 

twalk(root, print node); 

/* 

This routine compares two nodes, based on an 
alphabetical ordering of the string field. 

*1 

int 

node compare (node 1 , node2) 
struct node »nodel, *node2; 

( 

return strcmp(nodel — >string, node2—> string); 

/* 

This routine prints out a node, the first time 
twalk encounters it. 

*/ 
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void 

print_node(node, order, level) 
struct node **node; 

VISIT order; 
int level; 

{ 

if (order preorder II order == leaf) { 

(void) printf ("string = %20s, length = %d\n", 
(♦node)— >string, (*node)— > length); 


SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned by tsearch if there is not enough space available to 
create a new node. 

A NULL pointer is returned by tsearch, tfind and tdelete if rootp is NULL on 
entry. 

If the datum is found, both tsearch and tfind return a pointer to it. If not, 
tfind returns NULL, and tsearch returns a pointer to the inserted item. 

WARNINGS 

The root argument to twalk is one level of indirection less than the rootp argu- 
ments to tsearch and tdelete. 

There are two nomenclatures used to refer to the order in which tree nodes are 
visited. Tsearch uses preorder, postorder and endorder to respectively refer to 
visting a node before any of its children, after its left child and before its right, 
and after both its children. The alternate nomenclature uses preorder, inorder 
and postorder to refer to the same visits, which could result in some confusion 
over the meaning of postorder. 

BUGS 

If the calling function alters the pointer to the root, results are unpredictable. 
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NAME 

ttyname, isatty — find name of a terminal 

SYNOPSIS 

char *ttyname (fildes) 
int fildes; 

int isatty (fildes) 
int fildes; 

DESCRIPTION 

Ttyname returns a pointer to a string containing the null-terminated path name 
of the terminal device associated with file descriptor fildes. 

Isatty returns 1 if fildes is associated with a terminal device, 0 otherwise. 

FILES 

/dev/« 

DIAGNOSTICS 

Ttyname returns a NULL pointer if fildes does not describe a terminal device 
in directory /dev. 

BUGS 

The return value points to static data whose content is overwritten by each call. 
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NAME 

ttyslot — find the slot in the utmp file of the current user 

SYNOPSIS 

int ttyslot ( ) 

DESCRIPTION 

Ttyslot returns the index of the current user’s entry in the /etc/utmp file. This 
is accomplished by actually scanning the file /etc/inittab for the name of the 
terminal associated with the standard input, the standard output, or the error 
output (0, 1 or 2). 

FILES 

/etc/inittab 

/etc/utmp 

SEE ALSO 

getut(3C), ttyname(3C). 

DIAGNOSTICS 

A value of 0 is returned if an error was encountered while searching for the 
terminal name or if none of the above file descriptors is associated with a termi- 
nal device. 
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NAME 

ungetc — push character back into input stream 

SYNOPSIS 

#include <stdio.h> 

int ungetc (c, stream) 
int c; 

FILE ‘stream; 

DESCRIPTION 

Ungetc inserts the character c into the buffer associated with an input stream. 
That character, c, will be returned by the next getc(3S) call on that stream. 
Ungetc returns c, and leaves the file stream unchanged. 

One character of pushback is guaranteed, provided something has already been 
read from the stream and the stream is actually buffered. In the case that 
stream is stdin, one character may be pushed back onto the buffer without a 
previous read statement. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF. 

Fseek (3S) erases all memory of inserted characters. 

SEE ALSO 

fseek(3S), getc(3S), setbuf(3S). 

DIAGNOSTICS 

Ungetc returns EOF if it cannot insert the character. 
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NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs argument list 

SYNOPSIS 

#include <stdio.h> 

#include <varargs.h> 

int vprintf (format, ap) 
char *format; 
vajist ap; 

int vfprintf (stream, format, ap) 

FILE ‘stream; 
char ‘format; 
vajist ap; 

int vsprintf (s, format, ap) 
char »s, ‘format; 
vajist ap; 

DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as printf, fprintf, and sprintf 
respectively, except that instead of being called with a variable number of argu- 
ments, they are called with an argument list as defined by varargs { 5). 

EXAMPLE 

The following demonstrates how vfprintf could be used to write an error rou- 
tine. 

#include <stdio.h> 

#include < varargs. h> 


/» 

* error should be called like 

» error(function_name, format, argl, arg2...); 

»/ 

/•VARARGSO*/ 

void 

error (vaalist) 

/* Note that the function_name and format arguments cannot be 

* separately declared because of the definition of varargs. 

*/ 

va del 

( 

vajist args; 
char *fmt; 

vastart(args); 

/» print out name of function causing error »/ 

(void) fprintf (stderr, "ERROR in %s: ", va_arg(args, char »)); 
fmt = va_arg(args, char »); 

/• print out remainder of message */ 

(void)vfprintf(fmt, args); 
va_end(args); 

(void) abort ( ); 

} 

SEE ALSO 

vprintf(3X), varargs(5). 


10/84 


- I - 


10/84 



V 




BESSEL (3M) 


(Math Libraries) 


BESSEL (3M) 


NAME 

jO, j 1 , jn, yO, yl, yn — Bessel functions 

SYNOPSIS 

#include <math.h> 

double jO (x) 
double x; 

double jl (x) 
double x; 

double jn (n, x) 
int n; 
double x; 

double yO (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 

DESCRIPTION 

JO and jl return Bessel functions of x of the first kind of orders 0 and 1 
respectively. Jn returns the Bessel function of x of the first kind of order n. 

YO and yl return Bessel functions of x of the second kind of orders 0 and 1 
respectively. Yn returns the Bessel function of x of the second kind of order n. 
The value of x must be positive. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Non-positive arguments cause yO, yl and yn to return the value -HUGE and to 
set errno to EDOM. In addition, a message indicating DOMAIN error is printed 
on the standard error output. 

Arguments too large in magnitude cause jO,jl, yO and yl to return zero and to 
set errno to ERANGE. In addition, a message indicating TLOSS error is printed 
on the standard error output. 

These error-handling procedures may be changed with the function 
matherr( 3M). 
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NAME 

erf, erfc — error function and complementary error function 

SYNOPSIS 

#include <math.h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 


DESCRIPTION 

Erf returns the error function of x, defined as 



Erfc, which returns 1 .0 — erf(x), is provided because of the extreme loss of 
relative accuracy if erf(x) is called for large x and the result subtracted from 
1.0 (e.g., for x = 5, 12 places are lost). 


SEE ALSO 

exp(3M). 
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(Math Libraries) 


EXP(3M) 


NAME 

exp, log, log 10, pow, sqrt — exponential, logarithm, power, square root functions 

SYNOPSIS 

#include <math.h> 

double exp (x) 
double x; 

double log (x) 
double x; 

double loglO (x) 
double x; 

double pow (x, y) 
double x, y; 

double sqrt (x) 
double x; 

DESCRIPTION 

Exp returns e x . 

Log returns the natural logarithm of x. The value of x must be positive. 

LoglO returns the logarithm base ten of x. The value of x must be positive. 

Pow returns x l . If x is zero, y must be positive. If x is negative, y must be an 
integer. 

Sqrt returns the non-negative square root of x. The value of x may not be 
negative. 

SEE ALSO 

hypot(3M), matherr(3M), sinh(3M). 

DIAGNOSTICS 

Exp returns HUGE when the correct value would overflow, or 0 when the 
correct value would underflow, and sets errno to ERANGE. 

Log and loglO return -HUGE and set errno to EDOM when x is non-positive. 
A message indicating DOMAIN error (or SING error when x is 0) is printed on 
the standard error output. 

Pow returns 0 and sets errno to EDOM when x is 0 and y is non-positive, or 
when x is negative and y is not an integer. In these cases a message indicating 
DOMAIN error is printed on the standard error output. When the correct value 
for pow would overflow or underflow, pow returns ±HUGE or 0 respectively, 
and sets errno to ERANGE. 

Sqrt returns 0 and sets errno to EDOM when x is negative. A message indicat- 
ing DOMAIN error is printed on the standard error output. 

These error-handling procedures may be changed with the function 
matherri, 3M). 
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FLOOR (3M) 


NAME 

floor, ceil, fmod, fabs — floor, ceiling, remainder, absolute value functions 

SYNOPSIS 

#include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double x, y; 

double fabs (x) 
double x; 

DESCRIPTION 

Floor returns the largest integer (as a double-precision number) not greater 
than x. 

Ceil returns the smallest integer not less than x. 

Fmod returns the floating-point remainder of the division of x by y: zero if y 
is zero or if x/y would overflow; otherwise the number / with the same sign as 
x, such that x = iy + / for some integer and [/I < \y\. 

Fabs returns the absolute value of x, |x|. 

SEE ALSO 

abs(3C). 
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GAMMA (3M) 


NAME 

gamma — log gamma function 

SYNOPSIS 

#include <math.h> 

double gamma (x) 
double x; 

extern int signgam; 

DESCRIPTION 

CO 

Gamma returns In (| T( jc ) | ) , where r(x) is defined as Je ‘ t x x dt. The sign 

o 

of rU) is returned in the external integer signgam. The argument x may not 
be a non-positive integer. 

The following C program fragment might be used to calculate T: 

if ((y = gamma (x)) > LN_MAXDOUBLE) 
error 0; 

y = signgam * exp(y); 

where LN MAXDOUBLE is the least value that causes exp(3M) to return a 
range error, and is defined in the <values.h> header file. 

SEE ALSO 

exp(3M), matherr(3M), values(5). 

DIAGNOSTICS 

For non-negative integer arguments HUGE is returned, and errno is set to 
EDOM. A message indicating SING error is printed on the standard error out- 
put. 

If the correct value would overflow, gamma returns HUGE and sets errno to 
ERANGE. 

These error-handling procedures may be changed with the function 
mat herr (3M) . 
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(Math Libraries) 


HYPOTC3M) 


NAME 

hypot — Euclidean distance function 

SYNOPSIS 

#include <math.h> 

double hypot (x, y) 
double x, y; 

DESCRIPTION 

Hypot returns 

sqrt(x * x + y * y), 

taking precautions against unwarranted overflows. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE and sets errno to 
ERANGE. 

These error-handling procedures may be changed with the function 
matherri 3M). 
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(Math Libraries) 


MATHERR (3M) 


NAME 

matherr — error-handling function 

SYNOPSIS 

#include <math.h> 

int matherr (x) 
struct exception »x; 

DESCRIPTION 

Matherr is invoked by functions in the Math Library when errors are detected. 
Users may define their own procedures for handling errors, by including a func- 
tion named matherr in their programs. Matherr must be of the form described 
above. When an error occurs, a pointer to the exception structure x will be 
passed to the user-supplied matherr function. This structure, which is defined 
in the <math.h> header file, is as follows: 

struct exception { 
int type; 
char *name; 

double argl, arg2, retval; 

); 


The element type is an integer describing the type of error that has occurred, 
from the following list of constants (defined in the header file): 


DOMAIN 

SING 

OVERFLOW 

UNDERFLOW 

TLOSS 

PLOSS 


argument domain error 
argument singularity 
overflow range error 
underflow range error 
total loss of significance 
partial loss of significance 


The element name points to a string containing the name of the function that 
incurred the error. The variables argl and arg2 are the arguments with which 
the function was invoked. Retval is set to the default value that will be 
returned by the function unless the user’s matherr sets it to a different value. 


If the user’s matherr function returns non-zero, no error message will be 
printed, and errno will not be set. 


If matherr is not supplied by the user, the default error-handling procedures, 
described with the math functions involved, will be invoked upon error. These 
procedures are also summarized in the table below. In every case, errno is set 
to EDOM or ERANGE and the program continues. 


EXAMPLE 

#include <math.h> 


int 

matherr (x) 

register struct exception *x; 

( 

switch (x— >type) ( 
case DOMAIN: 

/* change sqrt to return sqrt ( — argl), not 0 */ 
if (!strcmp(x— >name, "sqrt")) { 

x— > retval = sqrt(— x— > arg 1 ) ; 

return (0); /* print message and set errno */ 

) 

case SING: 

/* all other domain or sing errors, print message and abort */ 
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(Math Libraries) 


MATHERR (3M) 


fprintf(stderr, "domain error in %s\n", x— >name); 
abort ( ); 
case PLOSS: 

/* print detailed error message »/ 
fprintf(stderr, "loss of significance in %s(%g) = %g\n", 
x— >name, x— >argl, x— >retval); 
return (1); /* take no other action */ 

) 

return (0); /* all other errors, execute default procedure */ 


DEFAULT ERROR HANDLING PROCEDURES 


Types of Errors 

type 

DOMAIN 

SING 

OVERFLOW 

UNDERFLOW 

TLOSS 

PLOSS 

errno 

EDOM 

EDOM 

ERANGE 

ERANGE 

ERANGE 

ERANGE 

BESSEL: 

- 

- 

- 

- 

M, 0 

• 


M, -H 

- 

- 

- 

- 

- 

EXP: 

- 

- 

H 

0 

- 

- 

LOG, LOG 10: 







(arg < 0) 

M, -H 

- 

- 

- 

- 

- 

(arg = 0) 

- 

M, -H 

- 

- 

- 

- 

POW: 

- 

- 

±H 

0 

- 

- 

neg ** non-int 

M, 0 

- 

- 

- 

- 

- 

0 ** non-pos 







3QRT: 

M, 0 

- 

- 

- 

- 

- 

GAMMA: 

- 

M, H 

H 

- 

- 

- 

HYPOT: 

- 

- 

H 

- 

- 

- 

5INH: 

- 

- 

±H 

- 

- 

- 

COSH: 

- 

- 

H 

- 

- 

- 

SIN, COS, TAN: - 

- 

- 

- 

M, 0 

* 



- 

- 

- 

- 

- 



ABBREVIATIONS 

* As much as possible of the value is returned. 
M Message is printed (EDOM error) . 

H HUGE is returned. 

— H —HUGE is returned. 

±H HUGE or —HUGE is returned. 

0 0 is returned. 
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SINH (3M) 


(Math Libraries) 


SINH (3M) 


NAME 

sinh, cosh, tanh - hyperbolic functions 


SYNOPSIS 

#include < math.h > 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 


DESCRIPTION 

Sinh, cosh, and tanh return, respectively, the hyberbolic 
tangent of their argument. 


sine, cosine and 


SEE ALSO 

matherr(3M). 


DIAGNOSTICS 

Sinh and cosh return HUGE (and sinh may return -HUGE for negative x) 
when the correct value would overflow and set errno to ERANGE. 

These error-handling procedures may be changed with the function 


matherr(3M). 
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(Math Libraries) 


TRIG (3M) 


NAME 

sin, cos, tan, asin, acos, atan, atan2 — trigonometric functions 

SYNOPSIS 

#include <math.h> 

double sin (x) 
double x; 

double cos (x) 
double x; 

double tan (x) 
double x; 

double asin (x) 
double x; 

double acos (x) 
double x; 

double atan (x) 
double x; 

double atan2 (y, x) 
double y, x; 

DESCRIPTION 

Sin, cos and tan return respectively the sine, cosine and tangent of their argu- 
ment, x, measured in radians. 

Asin returns the arcsine of x, in the range —ir/2 to 7r/2. 

Acos returns the arccosine of x, in the range 0 to ir. 

Atan returns the arctangent of x, in the range — rr/2 to ir/2. 

Atan2 returns the arctangent of y/x, in the range — it to tt, using the signs of 
both arguments to determine the quadrant of the return value. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Sin, cos, and tan lose accuracy when their argument is far from zero. For 
arguments sufficiently large, these functions return zero when there would oth- 
erwise be a complete loss of significance. In this case a message indicating 
TLOSS error is printed on the standard error output. For less extreme argu- 
ments causing partial loss of significance, a PLOSS error is generated but no 
message is printed. In both cases, errno is set to ERANGE. 

If the magnitude of the argument of asin or acos is greater than one, or if both 
arguments of atan2 are zero, zero is returned and errno is set to EDOM. In 
addition, a message indicating DOMAIN error is printed on the standard error 
output. 

These error-handling procedures may be changed with the function 
matherr(3M) . 
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ASSERT (3X) 


NAME 

assert - verify program assertion 

SYNOPSIS 

#include < assert. h> 

assert (expression) 
int expression; 

DESCRIPTION 

This macro is useful for putting diagnostics into programs. When it is exe- 
cuted, if expression is false (zero), assert prints 

“Assertion failed: expression , file xyz, line nnn” 

on the standard error output and aborts. In the error message, xyz is the name 
of the source file and nnn the source line number of the assert statement. 

Compiling with the preprocessor option — DNDEBUG (see cpp( 1)), or with the 
preprocessor control statement “#define NDEBUG” ahead of the “#include 
<assert.h>” statement, will stop assertions from being compiled into the pro- 
gram. 

SEE ALSO 

abort(3C). 

cpp(l) in the 3B2 Computer System C Programming Language Utilities. 
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(Specialized Libraries) 


CURSES (3X) 


NAME 

curses — CRT screen handling and optimization package 


SYNOPSIS 

#include <curses.h> 

cc [ flags ] files — lcurses t libraries ] 

DESCRIPTION 

These routines give the user a method of updating screens with reasonable 
optimization. In order to initialize the routines, the routine initscrO must be 
called before any of the other routines that deal with windows and screens are 
used. The routine endwinO should be called before exiting. To get character- 
at-a-time input without echoing, (most interactive, screen oriented-programs 
want this) after calling initscrO you should call “nonlO; cbreakO; noechoO;” 

The full curses interface permits manipulation of data structures called win- 
dows which can be thought of as two dimensional arrays of characters 
representing all or part of a CRT screen. A default window called stdscr is sup- 
plied, and others can be created with newwin. Windows are referred to by vari- 
ables declared “WINDOW the type WINDOW is defined in curses. h to be a 
C structure. These data structures are manipulated with functions described 
below, among which the most basic are move, and addch. (More general ver- 
sions of these functions are included with names beginning with ‘w’, allowing 
you to specify a window. The routines not beginning with ‘w’ affect stdscr.) 
Then refreshO is called, telling the routines to make the users CRT screen look 
like stdscr. 

Mini-Curses is a subset of curses which does not allow manipulation of more 
than one window. To invoke this subset, use -DMINICURSES as a cc option. 
This level is smaller and faster than full curses. 

If the environment variable TERMINFO is defined, any program using curses 
will check for a local terminal definition before checking in the standard place. 
For example, if the standard place is /usr/lib/terminfo, and TERM is set to 
“vtlOO”, then normally the compiled file is found in /usr/lib/terminfo/v/vtlOO. 
(The “v” is copied from the first letter of “vtlOO” to avoid creation of huge 
directories.) However, if TERMINFO is set to /usr/mark/myterms, curses will 
first check /opusr/mark/myterms/v/vtlOO, and if that fails, will then check 
/usr/lib/terminfo/v/vtlOO. This is useful for developing experimental 
definitions or when write permission in /usr/lib/terminfo is not available. 


SEE ALSO 

terminfo(4). 

3B2 Computer System Terminal Information Utilities Guide. 


FUNCTIONS 

Routines listed here may be called when using the full curses. Those marked 
with an asterisk may be called when using Mini-Curses. 


addch (ch) * 

addstr(str)* 

attroff(attrs)* 

attron(attrs)* 

attrset(attrs)* 

baudrateO* 

beepO* 

box (win, vert, hor) 


clear 0 


add a character to stdscr (like putchar) 

(wraps to next line at end of line) 

calls addch with each character in str 

turn off attributes named 

turn on attributes named 

set current attributes to attrs 

current terminal speed 

sound beep on terminal 

draw a box around edges of win 

vert and hor are chars to use for vert, and 

hor. edges of box 

clear stdscr 


10/84 


- 1 - 


10/84 



CURSES (3X) 


CURSES (3X) 

clearok(win, bf) 
clrtobotO 
clrtoeolO 
cbreakO* 
delayoutput (ms) * 
delchO 
deletelnO 
delwin(win) 
doupdateO 
echoO* 
endwinO* 
erase 0 
erasecharO 
fixtermO 
fiashO 
flushinpO* 
getchO* 
getstr(str) 
gettmodeO 
getyxCwin, y, x) 
has_ic() 
hasilO 
idlok(win, bf)* 
inchO 
initscrO* 
insch (c) 
insertlnO 
intrfiush(win, bf) 
keypad (win, bf) 
killcharO 
leaveok(win, flag) 

longnameO 
meta(win, flag)* 
move(y, x)* 
mvaddch(y, x, ch) 
mvaddstr(y, x, str) 
mvcur(oldrow, oldcol, newrow, newcoDlow level cursor motion 
mvdelch(y, x) like delch, but move(y, x) first 

mvgetch(y, x) etc. 

mvgetstr(y, x, str) 
mvinch(y, x) 
mvinsch(y, x, c) 
mvprintw(y, x, fmt, args) 
mvscanw(y, x, fmt, args) 
mvwaddch(win, y, x, ch) 
mvwaddstr(win, y, x, str) 
mvwdelch(win, y, x) 
mvwgetch(win, y, x) 
mvwgetstr(win, y, x, str) 
mvwin(win, by, bx) 
mvwinch(win, y, x) 
mvwinsch(win, y, x, c) 
mvwprintw(win, y, x, fmt, args) 
mvwscanw(win, y, x, fmt, args) 

newpad(nlines, ncols) create a new pad with given dimensions 


(Specialized Libraries) 

clear screen before next redraw of win 
clear to bottom of stdscr 
clear to end of line on stdscr 
set cbreak mode 

insert ms millisecond pause in output 
delete a character 
delete a line 
delete win 

update screen from all wnooutrefresh 
set echo mode 
end window modes 
erase stdscr 

return user’s erase character 
restore tty to "in curses" state 
flash screen or beep 
throw away any typeahead 
get a char from tty 
get a string through stdscr 
establish current tty modes 
get (y, x) co-ordinates 
true if terminal can do insert character 
true if terminal can do insert line 
use terminal’s insert/delete line if bf != 0 
get char at current (y, x) co-ordinates 
initialize screens 
insert a char 
insert a line 

interrupts flush output if bf is TRUE 
enable keypad input 
return current user’s kill character 
OK to leave cursor anywhere after refresh if 
flag!=0 for win, otherwise cursor must be left 
at current position, 
return verbose name of terminal 
allow meta characters on input if flag != 0 
move to (y, x) on stdscr 
move(y, x) then addch(ch) 
similar... 
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(Specialized Libraries) CURSES (3X) 

newterm(type, fd) 

set up new terminal of given type to output on fd 

newwin (lines, cols, begin_y, begin_x) create a new window 

nlO* 

set newline mapping 

nocbreakO* 

unset cbreak mode 

nodelay(win, bf) 

enable nodelay input mode through getch 

noechoO* 

unset echo mode 

nonlO* 

unset newline mapping 

noraw ()* 

unset raw mode 

overlay (win 1, win2) 

overlay winl on win2 

overwrite(winl, win2) 

overwrite winl on top of win2 

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

like prefresh but with no output until doupdate called 

prefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

refresh from pad starting with given upper left corner of pad 
with output to given portion of screen 

printw(fmt, argl, arg2, ...) 

printf on stdscr 

raw()* 

set raw mode 

refreshO* 

make current screen look like stdscr 

resettermO* 

set tty modes to "out of curses” state 

resettyO* 

reset tty flags to stored value 

savetermO* 

save current modes as "in curses" state 

savettyO* 

store current tty flags 

scanw(fmt, argl, arg2, ...) 

scanf through stdscr 

scroll (win) 

scroll win one line 

scrollok(win, flag) 

allow terminal to scroll if flag != 0 

setterm(new) 

now talk to terminal new 

setscrreg(t, b) 

set user scrolling region to lines t through b 

setterm(type) 

establish terminal with given type 

setupterm(term, filenum, errret) 

standendO* 

clear standout mode attribute 

standoutO* 

set standout mode attribute 

subwin (win, lines, cols, begin_y, begin_x) create a subwindow 

touchwin(win) 

change all of win 

traceoffO 

turn off debugging trace output 

traceonO 

turn on debugging trace output 

typeahead(fd) 

use file descriptor fd to check typeahead 

unctrl (ch)* 

printable version of ch 

waddch(win, ch) 

add char to win 

waddstr(win, str) 

add string to win 

wattroflXwin, attrs) 

turn off attrs in win 

wattron(win, attrs) 

turn on attrs in win 

wattrset(win, attrs) 

set attrs in win to attrs 

wclear(win) 

clear win 

wclrtobot(win) 

clear to bottom of win 

wclrtoeol (win) 

clear to end of line on win 

wdelch(win, c) 

delete char from win 

wdeleteln(win) 

delete line from win 

werase(win) 

erase win 

wgetch(win) 

get a char through win 

wgetstr(win, str) 

get a string through win 

winch (win) 

get char at current (y, x) in win 

winsch(win, c) 

insert char into win 

winsertln(win) 

insert line into win 

wmove(win, y, x) 

set current (y, x) co-ordinates on win 

wnoutrefresh(win) 

refresh but no screen output 

wprintw(win, fmt, argl, arg2, ...) printf on win 

wrefresh(win) 

make screen look like win 
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CURSES (3X) 


wscanw(win, fmt, argl, arg2, ...) scanf through win 
wsetscrreg(win, t, b) set scrolling region of win 

wstandend(win) clear standout attribute in win 

wstandout(win) set standout attribute in win 

TERMINFO LEVEL ROUTINES 

These routines should be called by programs wishing to deal directly with the 
terminfo database. Due to the low level of this interface, it is discouraged. Ini- 
tially, setupterm should be called. This will define the set of terminal depen- 
dent variables defined in terminfo (4). The include files <curses.h> and 
<term.h> should be included to get the definitions for these strings, numbers, 
and flags. Parmeterized strings should be passed through tparm to instantiate 
them. All terminfo strings (including the output of tparm) should be printed 
with tputs or putp . Before exiting, resetterm should be called to restore the tty 
modes. (Programs desiring shell escapes or suspending with control Z can call 
resetterm before the shell is called and fixterm after returning from the shell.) 
fixtermO restore tty modes for terminfo use 

(called by setupterm) 

resetterm 0 reset tty modes to state before program entry 

setupterm (term, fd, rc) read in database. Terminal type is the 

character string term , all output is to UNIX System file 
descriptor fd. A status value is returned in the 
integer pointed to by rc: 1 is normal. The simplest 
call would be setupterm(0, I, 0) which uses all the defaults, 
tparm (str, pi, p2, .... p9) instantiate string str with parms pj. 
tputs (str, affcnt, putc) apply padding info to string str. 

ajfcnt is the number of lines affected, or 1 if 
not applicable. Putc is a putchar-like function 
to which the characters are passed, one at a time. 
putp(str) handy function that calls tputsfstr, 1, putchar). 

vidputs(attrs, putc) output the string to put terminal in video attribute 

mode attrs, which is any combination of the attributes 
listed below. Chars are passed to putchar-like function putc. 
vidattr (attrs) Like vidputs but outputs through putchar 

TERMCAP COMPATIBILITY ROUTINES 

These routines were included as a conversion aid for programs that use 

termcap. Their parameters are the same as for termcap. They are emulated 

using the terminfo database. They may go away at a later date. 

tgetent(bp, name) look up termcap entry for name 

tgetflag(id) get boolean entry for id 

tgetnum(id) get numeric entry for id 

tgetstr(id, area) get string entry for id 

tgoto(cap, col, row) apply parms to given cap 

tputs (cap, affcnt, fn) apply padding to cap calling fn as putchar 

ATTRIBUTES 

The following video attributes can be passed to the functions 

attron,attroff,attrset. 

AJSTANDOUT Terminal’s best highlighting mode 

A UNDERLINE Underlining 

A_REVERSE Reverse video 

AJBLINK Blinking 

AJDIM Half bright 

A BOLD Extra bright or bold 

A_BLANK Blanking (invisible) 

APROTECT Protected 

A ALTCHARSET Alternate character set 
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CURSES (3X) 


FUNCTION KEYS 

The following function keys might be returned by getch if keypad has been 
enabled. Note that not all of these are currently supported, due to lack of 
definitions in terminfo or the terminal not transmitting a unique code when the 
key is pressed. 


Name 

Value 

Key name 

KEYBREAK 

0401 

break key (unreliable) 

KEYDOWN 

0402 

The four arrow keys ... 

KEYUP 

0403 


KEYLEFT 

0404 


KEY RIGHT 

0405 


KEYHOME 

0406 

Home key (upward+left arrow) 

KEYBACKSPACE 

0407 

backspace (unreliable) 

KEY F0 

0410 

Function keys. Space for 64 is reserved. 

KEY F(n) 

(KEY_F0+(n)) 

Formula for fn. 

KEYDL 

0510 

Delete line 

KEYIL 

0511 

Insert line 

KEY DC 

0512 

Delete character 

KEYJC 

0513 

Insert char or enter insert mode 

KEYEIC 

0514 

Exit insert char mode 

KEYCLEAR 

0515 

Clear screen 

KEYEOS 

0516 

Clear to end of screen 

KEY EOL 

0517 

Clear to end of line 

KEY SF 

0520 

Scroll 1 line forward 

KEY SR 

0521 

Scroll 1 line backwards (reverse) 

KEY NPAGE 

0522 

Next page 

KEY PPAGE 

0523 

Previous page 

KEYSTAB 

0524 

Set tab 

KEYCTAB 

0525 

Clear tab 

KEYCATAB 

0526 

Clear all tabs 

KEYENTER 

0527 

Enter or send (unreliable) 

KEYSRESET 

0530 

soft (partial) reset (unreliable) 

KEYRESET 

0531 

reset or hard reset (unreliable) 

KEYPRINT 

0532 

print or copy 

KEYLL 

0533 

home down or bottom (lower left) 


WARNING 

The plotting library plot l 3X) and the curses library curses (. 3X) both use the 
names eraseO and moveO. The curses versions are macros. If you need both 
libraries, put the ploti 3X) code in a different source file than the curses ( 3X) 
code, and/or #undef moveO and eraseO in the plot (3X) code. 
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LDAHREAD (3X) 


(Specialized Libraries) 


LDAHREAD (3X) 


NAME 

ldahread — read the archive header of a member of an archive file 

SYNOPSIS 

#include <stdio.h> 

#include <ar.h> 

#include <fllehdr.h> 

#include <ldfcn.h> 

int ldahread (ldptr, arhead) 

LDFILE *ldptr; 

ARCHDR *arhead; 

DESCRIPTION 

If TYPE (ldptr) is the archive file magic number, ldahread reads the archive 
header of the common object file currently associated with ldptr into the area 
of memory beginning at arhead. 

Ldahread returns SUCCESS or FAILURE. Ldahread will fail if TYPE (ldptr) 
does not represent an archive file, or if it cannot read the archive header. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4), ar(4). 
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LDCLOSE(3X) 


(Specialized Libraries) 


LDCLOSE (3X) 


NAME 

ldclose, ldaclose — close a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldclose (ldptr) 

LDFILE *ldptr; 

int ldaclose (ldptr) 

LDFILE * ldptr; 

DESCRIPTION 

Ldopeni 3X) and ldclose are designed to provide uniform access to both simple 
object files and object files that are members of archive files. Thus an archive 
of common object files can be processed as if it were a series of simple common 
object files. 

If TYPE (ldptr) does not represent an archive file, ldclose will close the file and 
free the memory allocated to the LDFILE structure associated with ldptr. If 
TYPE (ldptr) is the magic number of an archive file, and if there are any more 
files in the archive, ldclose will reinitialize OFFSET (ldptr) to the file address of 
the next archive member and return FAILURE. The LDFILE structure is 
prepared for a subsequent Idopeni. 3X). In all other cases, ldclose returns SUC- 
CESS. 

Ldaclose closes the file and frees the memory allocated to the LDFILE structure 
associated with ldptr regardless of the value of TYPE (ldptr). Ldaclose always 
returns SUCCESS. The function is often used in conjunction with Idaopen. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

fclose(3S), ldopen(3X), ldfcn(4). 
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LDFHREAD (3X) 


(Specialized Libraries) 


LDFHREAD (3X) 


NAME 

ldfhread — read the file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldfhread (Idptr, filehead) 

LDFILE "Idptr; 

FILHDR "filehead; 

DESCRIPTION 

Ldfhread reads the file header of the common object file currently associated 
with Idptr into the area of memory beginning at filehead. 

Ldfhread returns SUCCESS or FAILURE. Ldfhread will fail if it cannot read 
the file header. 

In most cases the use of ldfhread can be avoided by using the macro 
HEADER(Wprr) defined in Idfcn.h (see ldfcn (4)). The information in any 
field, fieldname , of the file header may be accessed using 

HEADER (Idptr) .fieldname. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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LDGETNAME(3X) 


(Specialized Libraries) 


LDGETNAME(3X) 


NAME 

ldgetname — retrieve symbol name for common object file symbol table entry 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

char *ldgetname (ldptr, symbol) 

LDFILE 'ldptr; 

SYMENT 'symbol; 

DESCRIPTION 

Ldgetname returns a pointer to the name associated with symbol as a string. 
The string is contained in a static buffer local to ldgetname that is overwritten 
by each call to ldgetname , and therefore must be copied by the caller if the 
name is to be saved. 

As of UNIX System V Release 2.0, the common object file format has been 
extended to handle arbitrary length symbol names with the addition of a 
“string table”. Ldgetname will return the symbol name associated with a sym- 
bol table entry for either a pre-UNIX System V Release 2.0 object file or a 
UNIX System V Release 2.0 object file. Thus, ldgetname can be used to 
retrieve names from object files without any backward compatibility problems. 
Ldgetname will return NULL (defined in stdio.h) for an object file if the name 
cannot be retrieved. This situation can occur: 

— if the “string table” cannot be found, 

— if not enough memory can be allocated for the string table, 

— if the string table appears not to be a string table (for example, if an 
auxiliary entry is handed to ldgetname that looks like a reference to a 
name in a non-existent string table), or 

— if the name’s offset into the string table is past the end of the string 
table. 

Typically, ldgetname will be called immediately after a successful call to 
Idtbread to retrieve the name associated with the symbol table entry filled by 
Idt bread. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 


10/84 


- 1 - 


10/84 



LDLREAD (3X) 


(Specialized Libraries) 


LDLREAD (3X) 


NAME 

ldlread, ldlinit, ldlitem — manipulate line number entries of a common object 
file function 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <linenum.h> 

#include <ldfcn.h> 

int ldlread (ldptr, fcnindx, linenum, linent) 

LDFILE *ldptr; 

long fcnindx; 

unsigned short linenum; 

LINENO linent; 

int ldlinit(ldptr, fcnindx) 

LDFILE • ldptr; 
long fcnindx; 

int ldlitem (ldptr, linenum, linent) 

LDFILE *ldptr; 
unsigned short linenum; 

LINENO linent; 

DESCRIPTION 

Ldlread searches the line number entries of the common object file currently 
associated with ldptr. Ldlread begins its search with the line number entry for 
the beginning of a function and confines its search to the line numbers associ- 
ated with a single function. The function is identified by fcnindx , the index of 
its entry in the object file symbol table. Ldlread reads the entry with the smal- 
lest line number equal to or greater than linenum into linent. 

Ldlinit and ldlitem together perform exactly the same function as ldlread. 
After an initial call to ldlread or ldlinit, ldlitem may be used to retrieve a 
series of line number entries associated with a single function. Ldlinit simply 
locates the line number entries for (he function identified by fcnindx. Ldlitem 
finds and reads the entry with the smallest line number equal to or greater than 
linenum into linent. 

Ldlread , ldlinit, and ldlitem each return either SUCCESS or FAILURE. 
Ldlread will fail if there are no line number entries in the object file, if fcnindx 
does not index a function entry in the symbol table, or if it finds no line number 
equal to or greater than linenum. Ldlinit will fail if there are no line number 
entries in the object file or if fcnindx does not index a function entry in the 
symbol table. Ldlitem will fail if it finds no line number equal to or greater 
than linenum. 

The programs must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbindex(3X), ldfcn(4). 
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LDLSEEK (3X) 


(Specialized Libraries) 


LDLSEEK(3X) 


NAME 

ldlseek, ldnlseek — seek to line number entries of a section of a common object 
file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <Idfcn.h> 

int ldlseek (ldptr, sectindx) 

LDFILE * ldptr; 
unsigned short sectindx; 

int ldnlseek (ldptr, sectname) 

LDFILE • ldptr; 
char “sectname; 

DESCRIPTION 

Ldlseek seeks to the line number entries of the section specified by sectindx of 
the common object file currently associated with ldptr. 

Ldnlseek seeks to the line number entries of the section specified by sectname. 

Ldlseek and ldnlseek return SUCCESS or FAILURE. Ldlseek will fail if sec- 
tindx is greater than the number of sections in the object file; ldnlseek will fail 
if there is no section name corresponding with *sectname. Either function will 
fail if the specified section has no line number entries or if it cannot seek to the 
specified line number entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), idshread(3X), ldfcn(4). 
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LDOHSEEK(3X) 


(Specialized Libraries) 


LDOHSEEK(3X) 


NAME 

ldohseek — seek to the optional file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldohseek (ldptr) 

LDFILE *ldptr; 

DESCRIPTION 

Ldohseek seeks to the optional file header of the common object file currently 
associated with ldptr. 

Ldohseek returns SUCCESS or FAILURE. Ldohseek will fail if the object file 
has no optional header or if it cannot seek to the optional header. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfhread(3X), ldfcn(4). 



LDOPEN (3X) 


(Specialized Libraries) 


LDOPEN (3X) 


NAME 

ldopen, ldaopen — open a common object file for reading 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

LDFILE ‘ldopen (filename, ldptr) 
char •filename; 

LDFILE ‘ldptr; 

LDFILE *ldaopen (filename, oldptr) 
char ‘filename; 

LDFILE ‘oldptr; 

DESCRIPTION 

Ldopen and Idclose (3X) are designed to provide uniform access to both simple 
object files and object files that are members of archive files. Thus an archive 
of common object files can be processed as if it were a series of simple common 
object files. 

If ldptr has the value NULL, then ldopen will open filename and allocate and 
initialize the LDFILE structure, and return a pointer to the structure to the cal- 
ling program. 

If ldptr is valid and if TYPE (ldptr) is the archive magic number, ldopen will 
reinitialize the LDFILE structure for the next archive member of filename. 

Ldopen and Idclose ( 3X) are designed to work in concert. Ldclose will return 
FAILURE only when TYPE (ldptr) is the archive magic number and there is 
another file in the archive to be processed. Only then should ldopen be called 
with the current value of ldptr. In all other cases, in particular whenever a 
new filename is opened, ldopen should be called with a NULL ldptr argument. 

The following is a prototype for the use of ldopen and Idclose 1 3X). 

/ * for each filename to be processed •/ 

ldptr = NULL; 
do 


if ( (ldptr = ldopen (filename, ldptr)) != NULL ) 

/* check magic number */ 

/* process the file */ 

} 

} while (ldclose(ldptr) == FAILURE ); 

If the value of oldptr is not NULL, ldaopen will open filename anew and allo- 
cate and initialize a new LDFILE structure, copying the TYPE, OFFSET, and 
HEADER fields from oldptr. Ldaopen returns a pointer to the new LDFILE 
structure. This new pointer is independent of the old pointer, oldptr. The two 
pointers may be used concurrently to read separate parts of the object file. For 
example, one pointer may be used to step sequentially through the relocation 
information, while the other is used to read indexed symbol table entries. 
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LDOPEN (3X) 


(Specialized Libraries) 


LDOPEN (3X) 


Both Idopen and Idaopen open filename for reading. Both functions return 
NULL if filename cannot be opened, or if memory for the LDFILE structure 
cannot be allocated. A successful open does not insure that the given file is a 
common object file or an archived object file. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

fopen(3S), ldclose(3X), ldfcn(4). 
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LDRSEEK(3X) 


(Specialized Libraries) 


LDRSEEKC3X) 


NAME 

ldrseek, ldnrseek — seek to relocation entries of a section of a common object 
file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldrseek (ldptr, sectindx) 

LDFIF F *ldptr; 
unsigned short sectindx; 

int ldnrseek (ldptr, sectname) 

LDFILE • ldptr; 
char *sectname; 

DESCRIPTION 

Ldrseek seeks to the relocation entries of the section specified by sectindx of 
the common object file currently associated with ldptr. 

Ldnrseek seeks to the relocation entries of the section specified by sectname. 

Ldrseek and ldnrseek return SUCCESS or FAILURE. Ldrseek will fail if sec- 
tindx is greater than the number of sections in the object file; ldnrseek will fail 
if there is no section name corresponding with sectname. Either function will 
fail if the specified section has no relocation entries or if it cannot seek to the 
specified relocation entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopcn(3X), ldshread(3X), ldfcn(4). 
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LDSHREAD(3X) 


(Specialized Libraries) 


LDSHREAD(3X) 


NAME 

ldshread, ldnshread — read an indexed/named section header of a common 
object file 

SYNOPSIS 

#include <stdio.h> 

#include <fdehdr.h> 

#include <scnhdr.h> 

#include <ldfcn.h> 

int ldshread (ldptr, sectindx, secthead) 

LDFILE »Idptr; 
unsigned short sectindx; 

SCNHDR “secthead; 

int ldnshread (ldptr, sectname, secthead) 

LDFILE -ldptr; 
char -sectname; 

SCNHDR -secthead; 

DESCRIPTION 

Ldshread reads the section header specified by sectindx of the common object 
file currently associated with ldptr into the area of memory beginning at sect- 
head. 

Ldnshread reads the section header specified by sectname into the area of 
memory beginning at secthead. 

Ldshread and ldnshread return SUCCESS or FAILURE. Ldshread will fail if 
sectindx is greater than the number of sections in the object file; ldnshread will 
fail if there is no section name corresponding with sectname. Either function 
will fail if it cannot read the specified section header. 

Note that the first section header has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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LDSSEEK(3X) 


(Specialized Libraries) 


LDSSEEK (3X) 


NAME 

ldsseek, ldnsseek — seek to an indexed/named section of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <Idfcn.h> 

int ldsseek (ldptr, sectindx) 

LDFILE =■ ldptr; 
unsigned short sectindx; 

int ldnsseek (ldptr, sectname) 

LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

Ldsseek seeks to the section specified by sectindx of the common object file 
currently associated with ldptr. 

Ldnsseek seeks to the section specified by sectname. 

Ldsseek and ldnsseek return SUCCESS or FAILURE. Ldsseek will fail if sec- 
tindx is greater than the number of sections in the object file; ldnsseek will fail 
if there is no section name corresponding with sectname. Either function will 
fail if there is no section data for the specified section or if it cannot seek to the 
specified section. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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LDTBINDEX(3X) 


(Specialized Libraries) 


LDTBINDEX (3X) 


NAME 

ldtbindex — compute the index of a symbol table entry of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

long ldtbindex (ldptr) 

LDFILE * ldptr; 

DESCRIPTION 

Ldtbindex returns the (long) index of the symbol table entry at the current 
position of the common object file associated with ldptr. 

The index returned by ldtbindex may be used in subsequent calls to 
Idtbreadi 3X). However, since ldtbindex returns the index of the symbol table 
entry that begins at the current position of the object file, if ldtbindex is called 
immediately after a particular symbol table entry has been read, it will return 
the index of the next entry. 

Ldtbindex will fail if there are no symbols in the object file, or if the object file 
is not positioned at the beginning of a symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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LDTBREAD (3X) 


(Specialized Libraries) 


LDTBREAD (3X) 


NAME 

Idtbread — read an indexed symbol table entry of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <fllehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

int Idtbread (Idptr, symindex, symbol) 

LDFILE *ldptr; 
long symindex; 

SYMENT ‘symbol; 

DESCRIPTION 

Ldtbread reads the symbol table entry specified by symindex of the common 
object file currently associated with Idptr into the area of memory beginning at 
symbol. 

Ldtbread returns SUCCESS or FAILURE. Ldtbread will fail if symindex is 
greater than the number of symbols in the object file, or if it cannot read the 
specified symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbseek(3X), ldgetname(3X), ldfcn(4). 
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LDTBSEEK (3X) 


(Specialized Libraries) 


LDTBSEEK (3X) 


NAME 

ldtbseek — seek to the symbol table of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldtbseek (ldptr) 

LDFILE »ldptr; 

DESCRIPTION 

Ldtbseek seeks to the symbol table of the object file currently associated with 
ldptr. 

Ldtbseek returns SUCCESS or FAILURE. Ldtbseek will fail if the symbol table 
has been stripped from the object file, or if it cannot seek to the symbol table. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), Idopen(3X), ldtbread(3X), ldfcn(4). 
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LOGNAME(3X) 


(Specialized Libraries) 


LOGNAME(3X) 


NAME 

logname — return login name of user 

SYNOPSIS 

char *logname( ) 

DESCRIPTION 

Logname returns a pointer to the null-terminated login name; it extracts the 
SLOGNAME variable from the user’s environment. 

This routine is kept in /lib/libPW.a. 

FILES 

/etc/profile 

SEE ALSO 

profile(4), environ(5). 

env(l), login (1) in the 3B2 Computer System User Reference Manual. 

BUGS 

The return values point to static data whose content is overwritten by each call. 
This method of determining a login name is subject to forgery. 
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MALLOC (3X) 


(Specialized Libraries) 


MALLOC (3X) 


NAME 

malloc, free, realloc, calloc, mallopt, mallinfo — fast main memory allocator 

SYNOPSIS 

#include <ma!loc.h> 

char *malIoc (size) 
unsigned size; 

void free (ptr) 
char «ptr; 

char *realloc (ptr, size) 
char »ptr; 
unsigned size; 

char *calioc (nelem, elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfo (max) 
int max; 

DESCRIPTION 

Malloc and free provide a simple general-purpose memory allocation package, 
which runs considerably faster than the malloc (.30 package. It is found in the 
library “malloc”, and is loaded if the option lmalloc” is used with cc(l) or 
M(l). 

Malloc returns a pointer to a block of at least size bytes suitably aligned for 
any use. 

The argument to free is a pointer to a block previously allocated by malloc 4 , 
after free is performed this space is made available for further allocation, and 
its contents have been destroyed (but see mallopt below for a way to change 
this behavior). 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free. 

Realloc changes the size of the block pointed to by ptr to size bytes and 
returns a pointer to the (possibly moved) block. The contents will be 
unchanged up to the lesser of the new and old sizes. 

Calloc allocates space for an array of nelem elements of size elsize. The space 
is initialized to zeros. 

Mallopt provides for control over the allocation algorithm. The available 
values for cmd are: 

M MXFAST Set maxfast to value. The algorithm allocates all blocks below 
the size of maxfast in large groups and then doles them out 
very quickly. The default value for maxfast is 0. 

M NLBLKS Set numlblks to value. The above mentioned “large groups” 
each contain numlblks blocks. Numlblks must be greater than 
0. The default value for numlblks is 100. 

M GRAIN Set grain to value. The sizes of all blocks smaller than max- 
fast are considered to be rounded up to the nearest multiple of 
grain. Grain must be greater than 0. The default value of 
grain is the smallest number of bytes which will allow align- 
ment of any data type. Value will be rounded up to a multiple 
of the default when grain is set. 
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MALLOC (3X) 


(Specialized Libraries) 


MALLOC (3X) 


MKEEP Preserve data in a freed block until the next malloc, realloc , 

or calloc. This option is provided only for compatibility with 
the old version of malloc and is not recommended. 

These values are defined in the <malloc.h> header file. 

Mallopt may be called repeatedly, but may not be called after the first small 
block is allocated. 


Mallinfo provides instrumentation describing space usage. It returns the struc- 
ture: 


struct mallinfo ( 


int arena; 

/* 

int ordblks; 

/* 

int smblks; 

/* 

int hblkhd; 

/* 

int hblks; 

/* 

int usmblks; 

/* 

int fsmblks; 

/* 

int uordblks; 

/* 

int fordblks; 

/* 

int keepcost; 

/* 


/* 


total space in arena */ 
number of ordinary blocks */ 
number of small blocks */ 
space in holding block headers */ 
number of holding blocks */ 
space in small blocks in use */ 
space in free small blocks */ 
space in ordinary blocks in use */ 
space in free ordinary blocks */ 
space penalty if keep option */ 
is used */ 


This structure is defined in the <malloc.h> header file. 


Each of the allocation routines returns a pointer to space suitably aligned (after 
possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), malloc(3C). 


DIAGNOSTICS 

Malloc, realloc and calloc return a NULL pointer if there is not enough avail- 
able memory. When realloc returns NULL, the block pointed to by ptr is left 
intact. If mallopt is called after any allocation or if cmd or value are invalid, 
non-zero is returned. Otherwise, it returns zero. 

WARNINGS 

This package usually uses more data space than malloc ( 3C). 

The code size is also bigger than malloc (.30 . 

Note that unlike malloc (30, this package does not preserve the contents of a 
block when it is freed, unless the M KEEP option of mallopt is used. 
Undocumented features of malloc( 3C) have not been duplicated. 
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PLOT(3X) 


(Specialized Libraries) 


PL0T(3X) 


NAME 

plot — graphics interface subroutines 

SYNOPSIS 

openpl 0 

erase 0 

label (s) 
char *s; 

line (xl, yl, x2, y2) 
int xl, yl, x2, y2; 

circle (x, y, r) 
int x, y, r; 

arc (x, y, xO, yO, xl, yl) 
int x, y, xO, yO, xl, yl; 

move (x, y) 
int x, y; 

cont (x, y) 
int x, y; 

point (x, y) 
int x, y; 

linemod (s) 
char »s; 

space (xO, yO, xl, yl) 
int xO, yO, xl, yl; 

closepl 0 
DESCRIPTION 

These subroutines generate graphic output in a relatively device-independent 
manner. Space must be used before any of these functions to declare the 
amount of space necessary. See plot (4). Openpl must be used before any of 
the others to open the device for writing. Closepl flushes the output. 

Circle draws a circle of radius r with center at the point 6c, y) . 

Arc draws an arc of a circle with center at the point 6c, y) between the points 
(xO, yO) and 6 cl, yl). 

String arguments to label and linemod are terminated by nulls and do not con- 
tain new-lines. 


See plot (4) for a description of the effect of the remaining functions. 
The library files listed below provide several flavors of these routines. 


FILES 

/usr/lib/libplot.a 
/usr/lib/lib300.a 
/usr/lib/lib300s.a 
(usr/lib/lib450.a 
/ usr/lib/lib40 1 4.a 


produces output for tplotl 1G) filters 

for DASI 300 

for DASI 300s 

for DASI 450 

for TEKTRONIX 4014 
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PLOT(3X) 


(Specialized Libraries) 


PLOT(3X) 


SEE ALSO 

plot (4). 

graph(lG), stat(lG), tplot(lG) in the 3B2 Computer System Graphics Utili- 
ties Guide. 

WARNINGS 

In order to compile a program containing these functions in file.c it is necessary 
to use “cc file.c — lplot”. 

In order to execute it, it is necessary to use “a.out | tplot”. 

The above routines use <stdio.h>, which causes them to increase the size of 
programs, not otherwise using standard I/O, more than might be expected. 


- 2 - 


10/84 


10/84 



REGCMP(3X) 


(Specialized Libraries) 


REGCMP(3X) 


NAME 

regcmp, regex — compile and execute regular expression 
SYNOPSIS 

char *regcmp (stringl [, string!, ...I, (char *)0) 
char *stringl, *string2, 

char *regex (re, subject!, retO, ...]) 
char *re, ‘subject, *retO, 

extern char * loci; 

DESCRIPTION 

Regcmp compiles a regular expression and returns a pointer to the compiled 
form. M alloc { 3C) is used to create space for the vector. It is the user’s 
responsibility to free unneeded space so allocated. A NULL return from 
regcmp indicates an incorrect argument. Regcmp 1 1) has been written to gen- 
erally preclude the need for this routine at execution time. 

Regex executes a compiled pattern against the subject string. Additional argu- 
ments are passed to receive values back. Regex returns NULL on failure or a 
pointer to the next unmatched character on success. A global character pointer 
loci points to where the match began. Regcmp and regex were mostly bor- 
rowed from the editor, ed( 1); however, the syntax and semantics have been 
changed slightly. The following are the valid symbols and their associated 
meanings. 

[ ] * ." These symbols retain their current meaning. 

$ Matches the end of the string; \n matches a new-line. 

— Within brackets the minus means through. For example, la— zl is 

equivalent to [abcd...xyzl. The — can appear as itself only if used as 
the first or last character. For example, the character class expression 
11-1 matches the characters 1 and — . 

+ A regular expression followed by + means one or more times. For 
example, 10— 91+ is equivalent to [0— 9H0— 9]». 

{m} {m,} {m,u} 

Integer values enclosed in {} indicate the number of times the preced- 
ing regular expression is to be applied. The value m is the minimum 
number and u is a number, less than 256, which is the maximum. If 
only m is present (e.g., {m}), it indicates the exact number of times 
the regular expression is to be applied. The value {m,} is analogous to 
{m, infinity} . The plus (+) and star (») operations are equivalent to 
{ 1 ,} and {0,} respectively. 

( ... )Sn 

The value of the enclosed regular expression is to be returned. The 
value will be stored in the (n+1) th argument following the subject 
argument. At most ten enclosed regular expressions are allowed. 
Regex makes its assignments unconditionally. 

( ... ) Parentheses are used for grouping. An operator, e.g., », +, {}, can 
work on a single character or a regular expression enclosed in 
parentheses. For example, (a*(cb+)»)S0. 

By necessity, all the above defined symbols are special. They must, therefore, 
be escaped to be used as themselves. 
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REGCMPC3X) 


(Specialized Libraries) 


REGCMP(3X) 


EXAMPLES 

Example 1: 

char ‘cursor, *newcursor, *ptr; 

newcursor = regex((ptr = regcmp("''\n", 0», cursor); 
free(ptr); 

This example will match a leading new-line in the subject string pointed at by 
cursor. 

Example 2: 

char ret0[9]; 

char *newcursor, *name; 

name = regcmp("([A— Za— z][A— za— zO— 9j{0,7})$0", 0); 
newcursor = regex(name, "123Testing321", retO); 

This example will match through the string “Testing3” and will return the 
address of the character after the last matched character (cursor+11). The 
string “Testing3” will be copied to the character array retO. 

Example 3: 

#include "file.i" 

char *string, ‘newcursor; 

newcursor = regex (name, string); 

This example applies a precompiled regular expression in file.i (see regcmpl 1)) 
against string. 

This routine is kept in /lib/libPW.a. 

SEE ALSO 

malloc(3C). 

ed(l) in the 3B2 Computer System User Reference Manual. 

regcmp(l) in the 3B2 Computer System C Programming Language Utilities. 

BUGS 

The user program may run out of memory if regcmp is called iteratively 
without freeing the vectors no longer required. The following user-supplied 
replacement for malloci 3C) reuses the same vector saving time and space: 

/* user’s program »/ 

char * 
malloc(n) 
unsigned n; 

{ 

static char rebuf[512l; 

return (n <= sizeof rebuf) ? rebuf : NULL; 

} 
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(Specialized Libraries) 


SPUTL (3X) 


NAME 

sputl, sgetl — access long integer data in a machine-independent fashion. 
SYNOPSIS 

void sputl (value, buffer) 
long value; 
char ‘buffer; 

long sgetl (buffer) 
char ‘buffer; 

DESCRIPTION 

Sputl takes the four bytes of the long integer value and places them in memory 
starting at the address pointed to by buffer. The ordering of the bytes is the 
same across all machines. 

Sgetl retrieves the four bytes in memory starting at the address pointed to by 
buffer and returns the long integer value in the byte ordering of the host 
machine. 

The combination of sputl and sgetl provides a machine-independent way of 
storing long numeric data in a file in binary form without conversion to charac- 
ters. 

A program which uses these functions must be loaded with the object-file 
access routine library libld.a. 
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(Specialized Libraries) 


VPRINTF(3X) 


NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs argument list 

SYNOPSIS 

#include <stdio.h> 

#include <varargs.h> 

int vprintf (format, ap) 
char ‘format; 
vajist ap; 

int vfprintf (stream, format, ap) 

FILE ‘stream; 
char ‘format; 
vajist ap; 

int vsprintf (s, format, ap) 
char *s, ‘format; 
vajist ap; 

DESCRIPTION 

vprintf , vfprintf , and vsprintf are the same as printf, fprintf, and sprintf 
respectively, except that instead of being called with a variable number of argu- 
ments, they are called with an argument list as defined by varargs (5) . 

EXAMPLE 

The following demonstrates how vfprintf could be used to write an error rou- 
tine. 

#include <stdio.h> 

#include <varargs.h> 


/» 

* error should be called like 

* error (function name, format, argl, arg2...); 

*/ 

/»VARARGS0»/ 

void 

error (va_alist) 

/* Note that the function name and format arguments cannot be 
» separately declared because of the definition of varargs. 

*/ 

va del 

{ 

vajist args; 
char *fmt; 

vastart(args); 

/* print out name of function causing error »/ 

(void) fprintf (stderr, "ERROR in %s: ", va_arg(args, char *)); 
fmt = va_arg(args, char »); 

/» print out remainder of message */ 

(void)vfprintf(fmt, args); 
vaend(args); 

(void) abort ( ); 

1 

SEE ALSO 

printf (3S), varargs (5). 
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(FORTRAN Programming Language Utilities) 


ABORT (3F) 


NAME 

abort — terminate Fortran program 

SYNOPSIS 

call abort ( ) 

DESCRIPTION 

Abort terminates the program which calls it, closing all open files truncated to 
the current position of the file pointer. The abort usually results in a core 
dump. 

DIAGNOSTICS 

When invoked, abort prints “Fortran abort routine called” on the standard 
error output. The message “abort - core dumped” is sent to the terminal. 

SEE ALSO 

abort (3 C). 
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ABS (3F) 


NAME 

abs, iabs, dabs, cabs, zabs — Fortran absolute value 

SYNOPSIS 

integer il, i2 
real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 
double complex dxl, dx2 

r2 = abs(rl) 

i2 = iabs(il) 
i2 = abs(il) 

dp2 = dabs(dpl) 
dp2 = abs(dpl) 

cx2 = cabs(cxl) 
cx2 = abs(cxl) 

dx2 = zabs(dxl) 
dx2 = abs(dxl) 

DESCRIPTION 

Abs is the family of absolute value functions. labs returns the integer absolute 
value of its integer argument. Dabs returns the double-precision absolute value 
of its double-precision argument. Cabs returns the complex absolute value of 
its complex argument. Zabs returns the double-complex absolute value of its 
double-complex argument. The generic form abs returns the type of its argu- 
ment. 

SEE ALSO 

floor (3 M). 
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ACOS (3F) 


(FORTRAN Programming Language Utilities) 


ACOSC3F) 


NAME 

acos, dacos — Fortran arccosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = acos(rl) 

dp2 = dacos(dpl) 
dp2 = acos(dpl) 

DESCRIPTION 

Acos returns the real arccosine of its real argument. Dacos returns the 
double-precision arccosine of its double-precision argument. The generic form 
acos may be used with impunity as its argument will determine the type of the 
returned value. 

SEE ALSO 

trig(3M). 
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(FORTRAN Programming Language Utilities) 


AIMAGC3F) 


NAME 

aimag, dimag — Fortran imaginary part of complex argument 

SYNOPSIS 

real r 

complex cxr 
double precision dp 
double complex cxd 

r = aimag (cxr) 
dp = dimag(cxd) 

DESCRIPTION 

Aimag returns the imaginary part of its single-precision complex argument. 
Dimag returns the double-precision imaginary part of its double-complex argu- 
ment. 
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NAME 

aint, dint — Fortran integer part intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = aint(rl) 

dp2 = dint(dpl) 
dp2 = aint(dpl) 

DESCRIPTION 

Aint returns the truncated value of its real argument in a real. Dint returns 
the truncated value of its double-precision argument as a double-precision 
value. Aint may be used as a generic function name, returning either a real or 
double-precision value depending on the type of its argument. 
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(FORTRAN Programming Language Utilities) 


ASIN (3F) 


NAME 

asin, dasin — Fortran arcsine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = asin(rl) 

dp2 = dasin(dpl) 
dp2 = asin(dpl) 

DESCRIPTION 

Asin returns the real arcsine of its real argument. Dasin returns the double- 
precision arcsine of its double-precision argument. The generic form asin may 
be used with impunity as it derives its type from that of its argument. 

SEE ALSO 

trig(3M). 
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(FORTRAN Programming Language Utilities) 


ATAN (3F) 


NAME 

atan, datan — Fortran arctangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = atan(rl) 

dp2 = datan(dpl) 
dp2 = atan(dpl) 

DESCRIPTION 

Atan returns the real arctangent of its real argument. Datan returns the 
double-precision arctangent of its double-precision argument. The generic form 
atan may be used with a double-precision argument returning a double- 
precision value. 

SEE ALSO 

trig(3M). 
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(FORTRAN Programming Language Utilities) 


ATAN2 (3F) 


NAME 

atan2, datan2 — Fortran arctangent intrinsic function 

SYNOPSIS 

real rl, r2, r3 

double precision dpi, dp2, dp3 
r3 = atan2(rl, r2) 

dp3 = datan2(dpl, dp2) 
dp3 = atan2(dpl, dp2) 

DESCRIPTION 

Atan2 returns the arctangent of argl/arg2 as a real value. Datan2 returns the 
double-precision arctangent of its double-precision arguments. The generic 
form atan2 may be used with impunity with double-precision arguments. 

SEE ALSO 

trig (3 M). 
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(FORTRAN Programming Language Utilities) 


BOOL (3F) 


NAME 

and, or, xor, not, lshift, rshift — Fortran Bitwise Boolean functions 

SYNOPSIS 

integer i, j, k 
real a, b, c 

k = and (i, j) 
c — or(a, b) 
j = xor(i, a) 
j = not(i) 
k = lshift (i, j) 
k = rshift (i, j) 

DESCRIPTION 

The generic intrinsic Boolean functions and, or and xor return the value of the 
binary operations on their arguments. Not is a unary operator returning the 
one’s complement of its argument. Lshift and rshift return the value of the 
first argument shifted left or right, respectively, the number of times specified 
by the second (integer) argument. 

The Boolean functions are generic; that is, they are defined for all data types as 
arguments and return values. Where required, the compiler will generate 
appropriate type conversions. 

NOTE 

Although defined for all data types, use of Boolean functions on any but integer 
data is bizarre and will probably result in unexpected consequences. 

BUGS 

The implementation of the shift functions may cause large shift values to 
deliver weird results. 

SEE ALSO 

mil(3F). 
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(FORTRAN Programming Language Utilities) 


CONJG (3F) 


NAME 

conjg, dconjg — Fortran complex conjugate intrinsic function 

SYNOPSIS 

complex cxl, cx2 
double complex dxl, dx2 

cx2 = conjg (cxl) 
dx2 = dconjg(dxl) 

DESCRIPTION 

Conjg returns the complex conjugate of its complex argument. Dconjg returns 
the double-complex conjugate of its double-complex argument. 
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(FORTRAN Programming Language Utilities) 


COS (3F) 


NAME 

cos, dcos, ccos — Fortran cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = cos(rl) 

dp2 = dcos(dpl) 
dp2 = cos(dpl) 

cx2 = ccos (cxl) 
cx2 = cos (cxl) 

DESCRIPTION 

Cos returns the real cosine of its real argument. Dcos returns the double- 
precision cosine of its double-precision argument. Ccos returns the complex 
cosine of its complex argument. The generic form cos may be used with 
impunity as its returned type is determined by that of its argument. 

SEE ALSO 

trig (3 M). 
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(FORTRAN Programming Language Utilities) 


COSH (3F) 


NAME 

cosh, dcosh — Fortran hyperbolic cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = cosh(rl) 

dp2 = dcosh(dpl) 
dp2 = cosh(dpl) 

DESCRIPTION 

Cosh returns the real hyperbolic cosine of its real argument. Dcosh returns the 
double-precision hyperbolic cosine of its double-precision argument. The gen- 
eric form cosh may be used to return the hyperbolic cosine in the type of its 
argument. 

SEE ALSO 

sinh(3M). 
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DIM(3F) (FORTRAN Programming Language Utilities) 

NAME 

dim, ddim, idim — positive difference intrinsic functions 

SYNOPSIS 

integer al, a2, a3 
a3 = idim(al, a2) 

real al, a2, a3 
a3 = dim(al, a2) 

double precision al, a2, a3 
a3 = ddimfal, a2) 

DESCRIPTION 

These functions return: 

al— a2 if al > a2 
0 if al < = a2 


DIM (3F) 
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(FORTRAN Programming Language Utilities) 


DPROD (3F) 


NAME 

dprod — double precision product intrinsic function 

SYNOPSIS 

real al, a2 

double precision a3 

a3 = dprod(al, a2) 

DESCRIPTION 

Dprod returns the double precision product of its real arguments. 
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(FORTRAN Programming Language Utilities) 


EXP(3F) 


NAME 

exp, dexp, cexp — Fortran exponential intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = exp(rl) 

dp2 = dexp(dpl) 
dp2 = exp(dpl) 

cx2 = cexp (cxl) 
cx2 = exp(cxl) 

DESCRIPTION 

Exp returns the real exponential function e x of its real argument. Dexp 
returns the double-precision exponential function of its double-precision argu- 
ment. Cexp returns the complex exponential function of its complex argument. 
The generic function exp becomes a call to dexp or cexp as required, depend- 
ing on the type of its argument. 

SEE ALSO 

exp(3M). 


10/84 


1 


10/84 



FTYPE(3F) 
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NAME 

int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx, ichar, char - explicit For- 
tran type conversion 

SYNOPSIS 

integer i, j 
real r, s 

double precision dp, dq 
complex cx 
double complex dcx 
character*/ ch 

i = int(r) 
i = int(dp) 
i = int(cx) 
i = int (dcx) 
i = ifix(r) 
i = idint (dp) 

r = real(i) 
r = real (dp) 
r = real(cx) 
r = real (dcx) 
r = float(i) 
r = sngl (dp) 

dp = dble(i) 
dp = dble(r) 
dp = dble(cx) 
dp = dble(dcx) 

cx = cmplx (i) 
cx = cmplx(i, j) 
cx = cmplx (r) 
cx = cmplx (r, s) 
cx = cmplx (dp) 
cx = cmplx (dp, dq) 
cx = cmplx(dcx) 

dcx = dcmplx(i) 
dcx = dcmplx(i, j) 
dcx = dcmplx (r) 
dcx = dcmplx (r, s) 
dcx = dcmplx (dp) 
dcx = dcmplx (dp, dq) 
dcx = dcmplx (cx) 

i = ichar(ch) 
ch = char(i) 

DESCRIPTION 

These functions perform conversion from one data type to another. 

The function int converts to integer form its real, double precision, complex, or 
double complex argument. If the argument is real or double precision, int 
returns the integer whose magnitude is the largest integer that does not exceed 
the magnitude of the argument and whose sign is the same as the sign of the 
argument (i.e. truncation). For complex types, the above rule is applied to the 
real part, ifix and idint convert only real and double precision arguments 
respectively. 
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(FORTRAN Programming Language Utilities) 


FTYPE(3F) 


The function real converts to real form an integer, double precision, complex, 
or double complex argument. If the argument is double precision or double 
complex, as much precision is kept as is possible. If the argument is one of the 
complex types, the real part is returned, float and sngl convert only integer and 
double precision arguments respectively. 

The function dble converts any integer, real, complex, or double complex argu- 
ment to double precision form. If the argument is of a complex type, the real 
part is returned. 

The function cmplx converts its integer, real, double precision, or double com- 
plex argument(s) to complex form. 

The function dcmplx converts to double complex form its integer, real, double 
precision, or complex argument(s). 

Either one or two arguments may be supplied to cmplx and dcmplx . If there is 
only one argument, it is taken as the real part of the complex type and an ima- 
ginary part of zero is supplied. If two arguments are supplied, the first is taken 
as the real part and the second as the imaginary part. 

The function ichar converts from a character to an integer depending on the 
character’s position in the collating sequence. 

The function char returns the character in the ;th position in the processor col- 
lating sequence where i is the supplied argument. 

For a processor capable of representing n characters, 

ichar (char (0) = i for 0 < i < n, and 

char (ichar (ch)) - ch for any representable character ch. 
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GETARG (3F) 


NAME 

getarg — return Fortran command-line argument 

SYNOPSIS 

character* N c 
integer i 

call getarg (i, c) 

DESCRIPTION 

Getarg returns the z'-th command-line argument of the current process. Thus, if 
a program were invoked via 

foo argl arg2 arg3 

getarg(2, c) would return the string “arg2” in the character variable c. 

SEE ALSO 

getopt(3C). 
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GETENV (3F) 


NAME 

getenv — return Fortran environment variable 

SYNOPSIS 

character*N c 

call getenv ("VARIABLEJNAME", c) 

DESCRIPTION 

Getenv returns the character-string value of the environment variable 
represented by its first argument into the character variable of its second argu- 
ment. If no such environment variable exists, all blanks will be returned. 

SEE ALSO 

getenv (3C), environ (5). 
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(FORTRAN Programming Language Utilities) 


IARGC (3F) 


NAME 

iargc — return the number of command line arguments 

SYNOPSIS 

integer i 

i = iargc ( ) 

DESCRIPTION 

The iargc function returns the number of command line arguments passed to 
the program. Thus, if a program were invoked via 

foo argl arg2 arg3 

iargc ( ) would return 3. 

SEE ALSO 

getarg(3F). 
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(FORTRAN Programming Language Utilities) 


INDEX (3F) 


NAME 

index — return location of Fortran substring 

SYNOPSIS 

character*Nl chi 
character*N2 ch2 
integer i 

i = index(chl, ch2) 

DESCRIPTION 

Index returns the location of substring ch2 in string chi . The value returned is 
the position at which substring ch2 starts, or 0 if it is not present in string chi . 
If N2 is greater than Nl, a zero is returned. 
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(FORTRAN Programming Language Utilities) 


LEN (3F) 


NAME 

len — return length of Fortran string 

SYNOPSIS 

character»N ch 
integer i 

i = len(ch) 

DESCRIPTION 

Len returns the length of string ch. 
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(FORTRAN Programming Language Utilities) 


LOG (3F) 


NAME 

log. alog, dlog, clog — Fortran natural logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = alog(rl) 
r2 = log(rl) 

dp2 = dlog(dpl) 
dp2 = log(dpl) 

cx2 = clog(cxl) 
cx2 = log(cxl) 

DESCRIPTION 

Alog returns the real natural logarithm of its real argument. Dlog returns the 
double-precision natural logarithm of its double-precision argument. Clog 
returns the complex logarithm of its complex argument. The generic function 
log becomes a call to alog , dlog , or clog depending on the type of its argu- 
ment. 

SEE ALSO 

exp(3M). 
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(FORTRAN Programming Language Utilities) 


LOG10(3F) 


NAME 

log 10, aloglO, dloglO — Fortran common logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = aloglO(rl) 
r2 = loglO(rl) 

dp2 = dloglO(dpl) 
dp2 = loglO(dpl) 

DESCRIPTION 

AloglO returns the real common logarithm of its real argument. DloglO 
returns the double-precision common logarithm of its double-precision argu- 
ment. The generic function loglO becomes a call to aloglO or dloglO depend- 
ing on the type of its argument. 

SEE ALSO 

exp(3M). 
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(FORTRAN Programming Language Utilities) 


MAX (3F) 


NAME 

max, maxO, amaxO, maxi, amaxl, dmaxl — Fortran maximum-value functions 

SYNOPSIS 

integer i, j, k, I 
real a, b, c, d 

double precision dpi, dp2, dp3 

I = max(i, j, k) 
c = max(a, b) 
dp = max(a, b, c) 
k = maxO(i, j) 
a = amaxO(i, j, k) 
i = maxi (a, b) 
d = amaxl (a, b, c) 
dp3 = dmaxl (dpi, dp2) 

DESCRIPTION 

The maximum-value functions return the largest of their arguments (of which 
there may be any number). Max is the generic form which can be used for all 
data types and takes its return type from that of its arguments (which must all 
be of the same type). MaxO returns the integer form of the maximum value of 
its integer arguments; amaxO , the real form of its integer arguments; maxi , 
the integer form of its real arguments; amaxl , the real form of its real argu- 
ments; and dmaxl , the double-precision form of its double-precision arguments. 

SEE ALSO 

min(3F). 
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(FORTRAN Programming Language Utilities) 


MCLOCK (3F) 


NAME 

mclock — return Fortran time accounting 

SYNOPSIS 

integer i 

i = mclock ( ) 

DESCRIPTION 

Mclock returns time accounting information about the current process and its 
child processes. The value returned is the sum of the current process’s user time 
and the user and system times of all child processes. 

SEE ALSO 

times(2), clock(3C), system(3F). 
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MIL(3F) 


NAME 

ior, iand, not, ieor, ishft, ishftc, ibits, btest, ibset, ibclr, mvbits — bit field mani- 
pulation intrinsic functions and subroutines from the Fortran Military Standard 
(M1L-STD-1753). 

SYNOPSIS 

integer i, k, I, m, n, len 
logical b 

i - ior(m, n) 
i = iand(m, n) 
i = not(m) 
i — ieor(m, n) 
i = ishft(m, k) 
i = ishftc (m, k, len) 
i = ibits (m, k, len) 
b = btest(n, k) 
i = ibset (n, k) 
i = ibclr(n, k) 
call mvbits(m, k, len, n, I) 

DESCRIPTION 

ior, iand, not, ieor — return the same results as and, or, not, xor as defined in 
6oo/(3 F). 

ishft, ishftc — m specifies the integer to be shifted, k specifies the shift count, 
k > 0 indicates a left shift, k = 0 indicates no shift, k < 0 indicates a right 
shift. In ishft, zeros are shifted in. In ishftc, the rightmost len bits are shifted 
circularly k bits. If k is greater than the machine word-size, ishftc will not 
shift. 

Bit fields are numbered from right to left and the rightmost bit position is zero. 
The length of the len field must be greater than zero. 

ibits — extract a subfield of len bits from m starting with bit position k and 

extending left for len bits. The result field is right justified and the remaining 

bits are set to zero. 

btest — The kth bit of argument n is tested. The value of the function is 
.TRUE, if the bit is a and 

ibset — the result is the value of n with the kth bit set to 1 . 
ibclr — the result is the value of n with the kth bit set to 0. 

mvbits — len bits are moved beginning at position k of argument m to position 1 
of argument n. 

SEE ALSO 

bool (3 F). 
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NAME 

min, minO, aminO, mini, aminl, dminl — Fortran minimum-value functions 

SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 

1 = min(i, j, k) 
c = min(a, b) 
dp = min (a, b, c) 
k = minO(i, j) 
a = aminO(i, j, k) 
i = mini (a, b) 
d = aminl (a, b, c) 
dp3 = dminl (dpi, dp2) 

DESCRIPTION 

The minimum-value functions return the minimum of their arguments (of 
which there may be any number). Min is the generic form which can be used 
for all data types and takes its return type from that of its arguments (which 
must all be of the same type). MinO returns the integer form of the minimum 
value of its integer arguments; aminO, the real form of its integer arguments; 
mini, the integer form of its real arguments; aminl, the real form of its real 
arguments; and dminl, the double-precision form of its double-precision argu- 
ments. 

SEE ALSO 

max(3F). 
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NAME 

mod, amod, dmod — Fortran remaindering intrinsic functions 

SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 
k = mod(i, j) 

r3 = amodCrl, r2) 
r3 = mod(rl, r2) 

dp3 = dmod (dpi, dp2) 
dp3 = mod (dpi, dp2) 

DESCRIPTION 

Mod returns the integer remainder of its first argument divided by its second 
argument. Amod and dmod return, respectively, the real and double-precision 
whole number remainder of the integer division of their two arguments. The 
generic version mod will return the data type of its arguments. 
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NAME 

irand, rand, srand — random number generator 

SYNOPSIS 

integer iseed, i, irand 
double precision x, rand 

call srand (iseed) 
i = irand ( ) 
x - rand( ) 

DESCRIPTION 

Irand generates successive pseudo-random integers in the range from 0 to 
2**15— 1. Rand generates pseudo-random numbers distributed in [0, 1.0]. 
Srand uses its integer argument to re-initialize the seed for successive invoca- 
tions of irand and rand. 

SEE ALSO 

rand(3C). 
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NAME 

anint, dnint, nint, idnint — Fortran nearest integer functions 

SYNOPSIS 

integer i 
real rl, r2 

double precision dpi, dp2 

r2 = anint(rl) 
i = nint(rl) 

dp2 = anint(dpl) 
dp2 = dnint(dpl) 

i = nint(dpl) 
i = idnint (dp 1 ) 

DESCRIPTION 

Anint returns the nearest whole real number to its real argument (i.e., 
int(a+0.5) if a ^ 0, int(a— 0.5) otherwise). Dnint does the same for its 
double-precision argument. Nint returns the nearest integer to its real argu- 
ment. Idnint is the double-precision version. Anint is the generic form of 
anint and dnint , performing the same operation and returning the data type of 
its argument. Nint is also the generic form of idnint. 
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NAME 

sign, isign, dsign — Fortran transfer-of-sign intrinsic function 

SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 

k = isign (i, j) 
k = sign(i, j) 

r3 = signCrl, r2) 

dp3 = dsign(dpl, dp2) 
dp3 = sign(dpl, dp2) 

DESCRIPTION 

Isign returns the magnitude of its first argument with the sign of its second 
argument. Sign and dsign are its real and double-precision counterparts, 
respectively. The generic version is sign and will devolve to the appropriate 
type depending on its arguments. 
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NAME 

signal — specify Fortran action on receipt of a system signal 

SYNOPSIS 

integer i, intfc 
external intfc 

call signal (i, intfc) 

DESCRIPTION 

The argument i specifies the signal to be caught. Signal allows a process to 
specify a function to be invoked upon receipt of a specific signal. The first 
argument specifies which fault or exception. The second argument specifies the 
function to be invoked. 

NOTE: The interrupt processing function, intfc, does not take an argument. 

SEE ALSO 

kill (2), signal (2). 
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NAME 

sin, dsin, csin — Fortran sine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = sin(rl) 

dp2 = dsin(dpl) 
dp2 = sin(dpl) 

cx2 = csin(cxl) 
cx2 = sin(cxl) 

DESCRIPTION 

Sin returns the real sine of its real argument. Dsin returns the double- 
precision sine of its double-precision argument. Csin returns the complex sine 
of its complex argument. The generic sin function becomes dsin or csin as 
required by argument type. 

SEE ALSO 

trig(3M). 


10/84 


- 1 - 


10/84 



SINH (3F) 


(FORTRAN Programming Language Utilities) 


SINH (3F) 


NAME 

sinh, dsinh — Fortran hyperbolic sine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = sinh(rl) 

dp2 = dsinh(dpl) 
dp2 = sinh(dpl) 

DESCRIPTION 

Sinh returns the real hyperbolic sine of its real argument. Dsinh returns the 
double-precision hyperbolic sine of its double-precision argument. The generic 
form sinh may be used to return a double-precision value when given a 
double-precision argument. 

SEE ALSO 

sinh(3M). 
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NAME 

sqrt, dsqrt, csqrt — Fortran square root intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = sqrt(rl) 

dp2 = dsqrt(dpl) 
dp2 = sqrt(dpl) 

cx2 = csqrt(cxl) 
cx2 = sqrt(cxl) 

DESCRIPTION 

Sqrt returns the real square root of its real argument. Dsqrt returns the 
double-precision square root of its double-precision argument. Csqrt returns 
the complex square root of its complex argument. Sqrt, the generic form, will 
become dsqrt or csqrt as required by its argument type. 

SEE ALSO 

exp(3M). 
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NAME 

lge, lgt, lie, lit — string comparison intrinsic functions 

SYNOPSIS 

character*N al, a2 
logical I 

I = lge(al, a2) 

1 = lgt(al, a2) 

1 = Ile(al, a2) 

1 = lltCal, a2) 

DESCRIPTION 

These functions return .TRUE, if the inequality holds and .FALSE, otherwise. 
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NAME 

system — issue a shell command from Fortran 
SYNOPSIS 

character»N c 

call system (c) 

DESCRIPTION 

System causes its character argument to be given to sMl) as input, as if the 
string had been typed at a terminal. The current process waits until the shell 
has completed. 

SEE ALSO 

exec (2), system (3S). 

sh (1) in the 3B2 Computer System User Reference Manual. 
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NAME 

tan, dtan — Fortran tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = tan(rl) 

dp2 = dtan(dpl) 
dp2 = tan(dpl) 

DESCRIPTION 

Tan returns the real tangent of its real argument. Dtan returns the double- 
precision tangent of its double-precision argument. The generic tan function 
becomes dtan as required with a double-precision argument. 

SEE ALSO 

trig (3 M). 
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NAME 

tanh, dtanh — Fortran hyperbolic tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = tanh(rl) 

dp2 = dtanh(dpl) 
dp2 = tanh(dpl) 

DESCRIPTION 

Tanh returns the real hyperbolic tangent of its real argument. Dtanh returns 
the double-precision hyperbolic tangent of its double-precision argument. The 
generic form tanh may be used to return a double-precision value given a 
double-precision argument. 

SEE ALSO 

sinh(3M). 
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NAME 

intro — introduction to file formats 
DESCRIPTION 

This section outlines the formats of various files. The C struct declarations for 
the file formats are given where applicable. Usually, these structures can be 
found in the directories /usr/include or /usr/include/sys. 

References of the type name{ 1M) refer to entries found in Section 1 of the 
UNIX System V Administration Utilities Guide. 
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NAME 

a.out — common assembler and link editor output 
DESCRIPTION 

The file name a.out is the output file from the assembler a,y(l) and the link edi- 
tor ld{ 1). Both programs will make a.out executable if there were no errors in 
assembling or linking and no unresolved external references. 

A common object file consists of a file header, a UNIX system header, a table 
of section headers, relocation information, (optional) line numbers, a symbol 
table, and a string table. The order is given below. 

File header. 

UNIX system header. 

Section 1 header. 

Section n header. 

Section 1 data. 

Section n data. 

Section 1 relocation. 

Section n relocation. 

Section 1 line numbers. 

Section n line numbers. 

Symbol table. 

String table. 

The last three parts of an object file (line numbers, symbol table and string 
table) may be missing if the program was linked with the — s option of ld(\) or 
if they were removed by strip (1). Also note that the relocation information 
will be absent if there were no unresolved external references after linking. 
The string table exists only if the symbol table contains symbols with names 
longer than eight characters. 

The sizes of each section (contained in the header, discussed below) are in 
bytes and are even. 

When an a.out file is loaded into memory for execution, three logical segments 
are set up: the text segment, the data segment (initialized data followed by 
uninitialized, the latter actually being initialized to all 0’s), and a stack. On 
the 3B2 computers the text segment starts at location 0x80800000. 

The a.out file produced by ld{ 1) by default has a number called the magic 
number 0413 in the first field of the UNIX system header. The headers (file 
header, UNIX system header, and section headers) are loaded at the beginning 
of the text segment and the text immediately follows the headers in the user 
address space. The first text address will equal the size of the headers, and will 
vary depending upon the number of section headers in the a.out file. In an 
a.out file with three sections (.text, .data, and .bss), the first text address is at 
0x808000A8 on the 3B2 computers. The text segment is not writable by the 
program; if other processes are executing the same a.out file, the processes will 
share a single text segment. 

The data segment starts at the next segment boundary (512k on the 3B2 com- 
puters) past the last text address. The first data address is determined by the 
following: If an a.out file were split into 8k chunks, one of the chunks would 
contain both the end of text and the beginning of data. When the core image 
is created, that chunk will appear twice; once at the end of text and once at the 
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beginning of data (with some unused space in between). The duplicated chunk 
of text that appears at the beginning of data is never executed; is is duplicated 
so that the operating system may bring in pieces of the file in multiples of the 
page size without having to realign the beginning of the data section to a page 
boundary. Therefore the first data address is the sum of the next segment 
boundary past the end of text plus the remainder of the last text address 
divided by 8k. 

On the 3B2 computer the stack begins at location 0xC0020000 and grows 
toward higher addresses. On all machines the stack is automatically extended 
as required. The data segment is extended only as requested by the brk( 2) sys- 
tem call. 

The value of a word in the text or data portions that is not a reference to an 
undefined external symbol is exactly the value that will appear in memory when 
the file is executed. If a word in the text involves a reference to an undefined 
external symbol, the storage class of the symbol-table entry for that word will 
be marked as an “external symbol”, and the section number will be set to 0. 
When the file is processed by the link editor and the external symbol becomes 
defined, the value of the symbol will be added to the word in the file. 

File Header 

The format of the filehdr header is 
struct filehdr 


unsigned short 

unsigned short 

long 

long 

long 

unsigned short 
unsigned short 


fmagic; /» 
fnscns; / * 
f timdat; / * 
fsymptr; / * 
fnsyms; /» 
f_opthdr; / * 
f flags; /* 


UNIX System Header 

The format of the UNIX system header is 


typedef struct aouthdr 


short 

magic; 

/* 

short 

vstamp; 

h 

long 

tsize; 

/* 

long 

dsize; 

/* 

long 

bsize; 

/* 

long 

entry; 

/* 

long 

textstart; 

/» 

long 

data_start; 

/* 


) AOUTHDR; 


magic number */ 
number of sections */ 
time and date stamp */ 
file ptr to symtab */ 

# symtab entries */ 
sizeof(opt hdr) */ 
flags */ 


magic number */ 
version stamp »/ 
text size in bytes, padded */ 
initialized data (.data) */ 
uninitialized data (.bss) */ 
entry point */ 

base of text used for this file */ 
base of data used for this file */ 
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Section Header 

The format of the section header is 

struct scnhdr 

{ 


char 

s name[SYMNMLEN];/» section name */ 

long 

s_paddr; 

/* physical address */ 

long 

s_vaddr; 

/* virtual address */ 

long 

ssize; 

/* section size */ 

long 

sscnptr; 

/* file ptr to raw data */ 

long 

s_relptr; 

/» file ptr to relocation */ 

long 

sjnnoptr; 

/» file ptr to line numbers */ 

unsigned short 

snreloc; 

/* # reloc entries */ 

unsigned short 

snlnno; 

/* # line number entries */ 

long 

sflags; 

/* flags */ 


}; 

Relocation 

Object files have one relocation entry for each relocatable reference in the text 
or data. If relocation information is present, it will be in the following format: 

struct reloc 

{ 

long r vaddr; /* (virtual) address of reference */ 

long r_symndx; /* index into symbol table */ 

short r_type; /* relocation type */ 

} > 

The start of the relocation information is sjelptr from the section header. If 
there is no relocation information, sjelptr is 0. 
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Symbol Table 

The format of each symbol in the symbol table is 

#define SYMNMLEN 8 

#define FILNMLEN 14 

#define SYMESZ 18 /* the size of a SYMENT */ 


struct syment 

{ 

union /» all ways to get a symbol name */ 

char _n_name[SYMNMLEN]; /* name of symbol */ 

struct 


long 
long 
} _n_n; 
char 
) _n; 

unsigned long 
short 

unsigned short 

char 

char 

}; 


_n_zeroes; /* == OL if in string table */ 
noffset; /* location in string table */ 

*_n_nptr[2]; /* allows overlaying */ 


n_value; 

nscnum; 

n_type; 

nsclass; 

nnumaux; 


/» value of symbol «/ 

/» section number »/ 

/* type and derived type */ 
/» storage class */ 

/* number of aux entries */ 


#define n_name 
#define n zeroes 
#define n offset 
#define n nptr 


n.nname 
n._n_n._n_zeroes 
n._n_n._n_offset 
n._n_nptr[ 1 ] 


Some symbols require more information than a single entry; they are followed 
by auxiliary entries that are the same size as a symbol entry. The format fol- 
lows. 
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union auxent { 
struct ( 

long xtagndx; 
union { 

struct { 

unsigned short xjnno; 
unsigned short x size; 

} xlnsz; 
long x_fsize; 

} xmisc; 
union ( 

struct { 

long xlnnoptr; 
long x_endndx; 

] x_fcn; 
struct { 

unsigned short x_dimen[DIMNUM]; 

] x_ary; 

} x_fcnary; 

unsigned short x tvndx; 

} x_sym; 

struct { 

char xfnametFILNMLEN]; 

} xfile; 

struct { 

long x_scnlen; 
unsigned short x_nreloc; 
unsigned short x_nlinno; 

} x_scn; 

struct ( 

long 

unsigned short 
unsigned short 

} x tv; 

}; 

Indexes of symbol table entries begin at zero. The start of the symbol table is 
fjymptr (from the file header) bytes from the beginning of the file. If the 
symbol table is stripped, f symptr is 0. The string table (if one exists) begins 
at fjymptr + ( fjisyms * SYMESZ) bytes from the beginning of the file. 

SEE ALSO 

brk(2), filehdr(4), ldfcn(4), linenum(4), reloc(4), scnhdr(4), syms(4). 
as(l), Id (1 ) in the 3B2 Computer System Software Generation System Utili- 
ties. 

cc(l) in the 3B2 Computer System C Programming Language Utilities. 


xtvfill; 

x_tvlen; 

x_tvran[2]; 
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NAME 

ar — common archive file format 
DESCRIPTION 

The archive command ar( 1) is used to combine several files into one. Archives 
are used mainly as libraries to be searched by the link editor ld( 1). 

Each archive begins with the archive magic string. 

#define ARMAG "!<arch>\n" /* magic string »/ 

#define SARMAG 8 /* length of magic string */ 

Each archive which contains common object files (see a. out (4)) includes an 
archive symbol table. This symbol table is used by the link editor ld( 1) to 
determine which archive members must be loaded during the link edit process. 
The archive symbol table (if it exists) is always the first file in the archive (but 
is never listed) and is automatically created and/or updated by ar. 

Following the archive magic string are the archive file members. Each file 
member is preceded by a file member header which is of the following format: 

#define ARFMAG "*\n" /« header trailer string */ 


struct ar 
( 

_hdr 

/* file member header */ 

l 

char 

ar_name[16]; 

/* '/' terminated file member name */ 

char 

ar_date[12]; 

/* file member date »/ 

char 

ar_uid[6l; 

/» file member user identification */ 

char 

ar j>id[6l; 

/♦ file member group identification */ 

char 

ar_mode[8]; 

/* file member mode (octal) »/ 

char 

ar_size[ 10]; 

/» file member size */ 

char 

ar_fmag[2]; 

/* header trailer string */ 


); 


All information in the file member headers is in printable ASCII. The numeric 
information contained in the headers is stored as decimal numbers (except for 
arjnode which is in octal). Thus, if the archive contains printable files, the 
archive itself is printable. 

The arjiame field is blank-padded and slash (/) terminated. The ar date field 
is the modification date of the file at the time of its insertion into the archive. 
Common format archives can be moved from system to system as long as the 
portable archive command ar( 1) is used. Conversion tools such as arcv( 1) and 
convert (. l) exist to aid in the transportation of non-common format archives to 
this format. 

Each archive file member begins on an even byte boundary; a newline is 
inserted between files if necessary. Nevertheless the size given reflects the 
actual size of the file exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 

If the archive symbol table exists, the first file in the archive has a zero length 
name (i.e., arnamelO] == ’/’). The contents of this file are as follows: 

• The number of symbols. Length: 4 bytes. 

• The array of offsets into the archive file. Length: 4 bytes * “the 
number of symbols”. 
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® The name string table. Length: ar_size — (4 bytes * (“the number of 
symbols” + l)). 

The number of symbols and the array of offsets are managed with sgetl and 
sputl. The string table contains exactly as many null terminated strings as 
there are elements in the offsets array. Each offset from the array is associated 
with the corresponding name from the string table (in order). The names in 
the string table are all the defined global symbols found in the common object 
files in the archive. Each offset is the location of the archive header for the 
associated symbol. 

SEE ALSO 

sputl (3X), a.out(4). 

ar(l), ld(l), strip(l) in the 3B2 Computer System Software Generation Sys- 
tem Utilities. 

WARNINGS 

Strip (.1) will remove all archive symbol entries from the header. The archive 
symbol entries must be restored via the ts option of the ar{ 1) command before 
the archive can be used with the link editor ld{ 1). 
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NAME 

checklist — list of file systems processed by fsck 

DESCRIPTION 

Checklist resides in directory /etc and contains a list of, at most, 15 special file 
names. Each special file name is contained on a separate line and corresponds 
to a file system. Each file system will then be automatically processed by the 
fsck{ \ M) command. 

SEE ALSO 

fsck(lM) in the 3B2 Computer System Administration Utilities Guide. 
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NAME 

core — format of core image file 
DESCRIPTION 

The UNIX system writes out a core image of a terminated process when any of 
various errors occur. See signal (. 2) for the list of reasons; the most common 
are memory violations, illegal instructions, bus errors, and user-generated quit 
signals. The core image is called core and is written in the process’s working 
directory (provided it can be; normal access controls apply). A process with an 
effective user ID different from the real user ID will not produce a core image. 

The first section of the core image is a copy of the system’s per-user data for 
the process, including the registers as they were at the time of the fault. The 
size of this section depends on the parameter usize , which is defined in 
/usr/include/sys/param.h. The remainder represents the actual contents of the 
user’s core area when the core image was written. If the text segment is read- 
only and shared, or separated from data space, it is not dumped. 

The format of the information in the first section is described by the user struc- 
ture of the system, defined in /usr/include/sys/user.h. The important stuff not 
detailed therein is the locations of the registers, which are outlined in 
/usr/include/sys/reg.h. 

SEE ALSO 

setuid(2), signal (2). 

crash(lM) in the 3B2 Computer System Administration Utilities Guide. 
sdb(l) in the 3B2 Computer System Extended Software Generation System 
Utilities. 
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NAME 

cpio — format of cpio archive 
DESCRIPTION 

The header structure, when the — c option of cpioll) is not used, is: 

struct ( 

short hmagic, 

hdev; 

ushort hino, 

hmode, 
huid, 
h_gid; 

short hnlink, 

hrdev, 
h_mtime[2], 
hnamesize, 
h_filesize[2]; 

char h_name[h_namesize rounded to word]; 

} Hdr; 

When the — c option is used, the header information is described by: 

sscanf(Chdr,"%6o%6o%6o%6o%6o%6o%6o%6o%l llo%6o%l llo%s", 
&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 
&Hdr.h_uid, &Hdr.hj>id, &Hdr.h_nlink, &Hdr.h_rdev, 
&Longtime, &Hdr.h_namesize,&Longfile,Hdr.h_name); 

Longtime and Longfile are equivalent to Hdr.hmtime and Hdr.h Jilesize, 
respectively. The contents of each file are recorded in an element of the array 
of varying length structures, archive , together with other items describing the 
file. Every instance of h magic contains the constant 070707 (octal). The 
items h dev through hjntime have meanings explained in stati 2). The length 
of the null-terminated path name h name, including the null byte, is given by 
hnamesize . 

The last record of the archive always contains the name TRAILER!!!. Special 
files, directories, and the trailer are recorded with h Jilesize equal to zero. 

SEE ALSO 

stat(2). 

cpio(l), find(l) in the 3B2 Computer System User Reference Manual. 
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NAME 

dir — format of directories 
SYNOPSIS 

#include <sys/dir.h> 

DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user may write 
into a directory. The fact that a file is a directory is indicated by a bit in the 
flag word of its i-node entry (see fs (4) ) . The structure of a directory entry as 
given in the include file is: 

#ifndef DIRSIZ 
#define DIRSIZ 14 
#endif 

struct direct 

{ 

inot d_ino; 

char d_name[DIRSIZ]; 

}; 

By convention, the first two entries in each directory are for . and ... The first 
is an entry for the directory itself. The second is for the parent directory. The 
meaning of .. is modified for the root directory of the master file system; there 
is no parent, so .. has the same meaning as .. 

SEE ALSO 

fs(4). 
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NAME 

filehdr — file header for common object files 

SYNOPSIS 

#include < filehdr.h > 

DESCRIPTION 

Every common object file begins with a 20-byte header. The following C struct 
declaration is used: 

struct filehdr 

( 

unsigned short fjnagic ; /* magic number */ 

unsigned short f nscns ; /* number of sections */ 

long f_timdat ; /» time & date stamp */ 

long fsymptr ; /* file ptr to symtab */ 

long fnsyms ; /* # symtab entries */ 

unsigned short f opthdr ; /* sizeoffopt hdr) */ 
unsigned short f flags ; /» flags */ 

); 

F symptr is the byte offset into the file at which the symbol table can be found. 

Its value can be used as the offset in fseekf. 3S) to position an I/O stream to the 
symbol table. The UNIX system optional header is 28-bytes. The valid magic 
numbers are given below: 

#define N3BMAGIC 0550 /* 3B20 computer »/ 

#define NTVMAGIC 0551 /* 3B20 computer */ 

#define VAXWRMAGIC 0570 /* VAX writable text segments */ 

#define VAXROMAGIC 0575 /* VAX readonly sharable text segments */ 

#define FBOMAG1C 0570 /* 3B5 and 3B2 computers */ 

The value in fjimdat is obtained from the time (2) system call. Flag bits 
currently defined are: 

#define F RELFLG 0000001 /* relocation entries stripped */ 

#define F EXEC 0000002 /* file is executable */ 

#define F LNNO 0000004 /« line numbers stripped */ 

#define F LSYMS 0000010 /» local symbols stripped »/ 

#define F MINMAL 0000020 /* minimal object file */ 

#define F UPDATE 0000040 /» update file, ogen produced */ 

#define F SWABD 0000100 /* file is "pre-swabbed" */ 

#define F ARI6WR 0000200 /* 16-bit DEC host */ 

#define F AR32WR 0000400 /« 32-bit DEC host */ 

#define F AR32W 0001000 /» non-DEC host */ 

#define F PATCH 0002000 /* "patch" list in opt hdr »/ 

#define F BM321D 0160000 /* WE 32000 family identification field »/ 

#define F BM32B 0020000 /» file contains WE 32100 code »/ 

#define F BM32RST 0010000 /* this object file contains restore 

work around [3B5/3B2 only] */ 

SEE ALSO 

time(2), fseek(3S), a.out(4). 
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NAME 

file system — format of system volume 
SYNOPSIS 

#include <sys/filsys.h> 

#include <sys/types.h> 

#include <sys/param.h> 

DESCRIPTION 

Every file system storage volume has a common format for certain vital infor- 
mation. Every such volume is divided into a certain number of 512-byte long 
sectors. Sector 0 is unused and is available to contain a bootstrap program or 
other information. 

Sector 1 is the super-block. The format of a super-block is: 

/* 

» Structure of the super-block 

*/ 


struct 

filsys 



i 

ushort 

sisize; 

/* size in blocks of i-list */ 


daddr_t 

s_fsize; 

/* size in blocks of entire volume */ 


short 

snfree; 

/* number of addresses in s free */ 


daddr_t 

sJreelNICFREEl; 

/* free block list */ 


short 

sninode; 

/♦ number of i-nodes in sjnode */ 


ino_t 

sinodelNICINODl; 

/* free i-node list */ 


char 

sflock; 

/* lock during free list manipulation */ 


char 

silock; 

/* lock during i-list manipulation */ 


char 

sfmod; 

/» super block modified flag */ 


char 

sronly; 

/* mounted read-only flag */ 


time_t 

stime; 

/* last super block update »/ 


short 

s_dinfo[4l; 

/» device information »/ 


daddr_t 

stfree; 

/* total free blocks*/ 


ino_t 

s_tinode; 

/* total free i-nodes */ 


char 

s_fname[6l; 

/* file system name */ 


char 

s_fpack[6l; 

/* file system pack name */ 


long 

s_fi 1 1 [ 1 2 ] ; 

/* ADJUST to make sizeof filsys 
be 512 */ 


long 

sstate; 

/* file system state */ 


long 

smagic; 

/* magic number to denote new 
file system */ 

}; 

long 

s_typ e ; 

/* type of new file system */ 

#define 

FsMAGIC 

Oxfdl 87e20 

/* s_magic number */ 

#define 

Fslb 

1 

/* 51 2-byte block */ 

#define 

Fs2b 

2 

/* 1024-byte block */ 

#define 

FsOKAY 

0x7c269d38 

/* s_state: clean */ 

#define 

FsACTIVE 

0x5e72d8 la 

/* s_state: active */ 

#define 

FsBAD 

0xcb096f43 

/* s state: bad root */ 


Sjype indicates the file system type. Currently, two types of file systems are 
supported: the original 512-byte oriented and the new improved 1024-byte 
oriented. S magic is used to distinguish the original 512-byte oriented file sys- 
tems from the newer file systems. If this field is not equal to the magic 
number, FsMAGIC, the type is assumed to be Fslb , otherwise the sjype field 
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is used. In the following description, a block is then determined by the type. 
For the original 512-byte oriented file system, a block is 512-bytes. For the 
1024-byte oriented file system, a block is 1024-bytes or two sectors. The 
operating system takes care of all conversions from logical block numbers to 
physical sector numbers. 

Sstate indicates the state of the file system. A cleanly unmounted, not dam- 
aged file system is indicated by the FsOKAY state. After a file system has been 
mounted for update, the state changes to FsACTIVE. A special case is used for 
the root file system. If the root file system appears damaged at boot time, it is 
mounted but marked FsBAD. Lastly, after a file system has been unmounted, 
the state reverts to FsOKAY. 

Sisize is the address of the first data block after the i-list; the i-list starts just 
after the super-block, namely in block 2; thus the i-list is s isize— 2 blocks long. 
S Jsize is the first block not potentially available for allocation to a file. These 
numbers are used by the system to check for bad block numbers; if an “impos- 
sible” block number is allocated from the free list or is freed, a diagnostic is 
written on the on-line console. Moreover, the free array is cleared, so as to 
prevent further allocation from a presumably corrupted free list. 

The free list for each volume is maintained as follows. The s Jree array con- 
tains, in s Jree[ 1], ..., s Jree[s jifree— 1], up to 49 numbers of free blocks. 
5 Jree[ 0] is the block number of the head of a chain of blocks constituting the 
free list. The first long in each free-chain block is the number (up to 50) of 
free-block numbers listed in the next 50 longs of this chain member. The first 
of these 50 blocks is the link to the next member of the chain. To allocate a 
block: decrement sjifree, and the new block is .? Jree\s jifree\. If the new 
block number is 0, there are no blocks left, so give an error. If sjifree became 
0, read in the block named by the new block number, replace sjifree by its 
first word, and copy the block numbers in the next 50 longs into the sjree 
array. To free a block, check if sjifree is 50; if so, copy sjifree and the s Jree 
array into it, write it out, and set sjifree to 0. In any event set .v Jree[s jifree] 
to the freed block’s number and increment sjifree. 

Sjfree is the total free blocks available in the file system. 

Sjiinode is the number of free i-numbers in the s inode array. To allocate an 
i-node: if sjiinode is greater than 0, decrement it and return 

sjnodeis ninode]. If it was 0, read the i-list and place the numbers of all free 
i-nodes (up to 100) into the sjnode array, then try again. To free an i-node, 
provided sjiinode is less than 100, place its number into s inodels ninode] and 
increment s ninode. If sjiinode is already 100, do not bother to enter the 
freed i-node into any table. This list of i-nodes is only to speed up the alloca- 
tion process; the information as to whether the i-node is really free or not is 
maintained in the i-node itself. 

S tinode is the total free i-nodes available in the file system. 

S Jlock and sjlock are flags maintained in the core copy of the file system 
while it is mounted and their values on disk are immaterial. The value of 
s Jmod on disk is likewise immaterial; it is used as a flag to indicate that the 
super-block has changed and should be copied to the disk during the next 
periodic update of file system information. 

S ronly is a read-only flag to indicate write-protection. 

Stime is the last time the super-block of the file system was changed, and is 
the number of seconds that have elapsed since 00:00 Jan. 1, 1970 (GMT). 
During a reboot, the s time of the super-block for the root file system is used to 
set the system’s idea of the time. 
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S Jname is the name of the file system and s Jpack is the name of the pack. 

I-numbers begin at 1, and the storage for i-nodes begins in block 2. Also, i- 
nodes are 64 bytes long. I-node 1 is reserved for future use. I-node 2 is 
reserved for the root directory of the file system, but no other i-number has a 
built-in meaning. Each i-node represents one file. For the format of an i-node 
and its flags, see inode (.4). 

FILES 

/ usr/include/sys/filsys.h 
/usr/include/ sys/stat.h 

SEE ALSO 

mount (2), inode (4). 

fsck(lM), fsdb(lM), mkfs(lM) in the 3B2 Computer System Administration 
Utilities Guide. 
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NAME 

fspec — format specification in text files 
DESCRIPTION 

It is sometimes convenient to maintain text files on the UNIX system with non- 
standard tabs, (i.e., tabs which are not set at every eighth column). Such files 
must generally be converted to a standard format, frequently by replacing all 
tabs with the appropriate number of spaces, before they can be processed by 
UNIX system commands. A format specification occurring in the first line of a 
text file specifies how tabs are to be expanded in the remainder of the file. 

A format specification consists of a sequence of parameters separated by blanks 
and surrounded by the brackets <: and :>. Each parameter consists of a 
keyletter, possibly followed immediately by a value. The following parameters 
are recognized: 

t tabs The t parameter specifies the tab settings for the file. The value of 

tabs must be one of the following: 

1. a list of column numbers separated by commas, indicating 
tabs set at the specified columns; 

2. a — followed immediately by an integer n, indicating tabs at 
intervals of n columns; 

3. a — followed by the name of a “canned” tab specification. 

Standard tabs are specified by t— 8, or equivalently, tl, 9, 17, 25, etc. 
The canned tabs which are recognized are defined by the tabs (1) 
command. 

s size The s parameter specifies a maximum line size. The value of size 

must be an integer. Size checking is performed after tabs have 
been expanded, but before the margin is prepended. 

m margin The m parameter specifies a number of spaces to be prepended to 
each line. The value of margin must be an integer. 

d The d parameter takes no value. Its presence indicates that the 

line containing the format specification is to be deleted from the 
converted file. 

e The e parameter takes no value. Its presence indicates that the 

current format is to prevail only until another format specification 
is encountered in the file. 

Default values, which are assumed for parameters not supplied, are t— 8 and 
mO. If the s parameter is not specified, no size checking is performed. If the 
first line of a file does not contain a format specification, the above defaults are 
assumed for the entire file. The following is an example of a line containing a 
format specification: 

* < :t5, 1 0, 1 5 s72:> « 

If a format specification can be disguised as a comment, it is not necessary to 
code the d parameter. 

Several UNIX system commands correctly interpret the format specification for 
a file. Among them is gath (see send( 1C)) which may be used to convert files 
to a standard format acceptable to other UNIX system commands. 

SEE ALSO 

ed(l), newform(l), tabs(l) in the 3B2 Computer System User Reference 
Manual. 
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NAME 

gettydefs — speed and terminal settings used by getty 
DESCRIPTION 

The /etc/gettydefs file contains information used by getty (1M) to set up the 
speed and terminal settings for a line. It supplies information on what the 
login prompt should look like. It also supplies the speed to try next if the user 
indicates the current speed is not correct by typing a <break> character. 

Each entry in /etc/gettydefs has the following format: 

label# initial-flags # final-flags # login-prompt #next-label 

Each entry is followed by a blank line. The various fields can contain quoted 
characters of the form \b, \n, \c, etc., as well as \nnn, where nnn is the octal 
value of the desired character. The various fields are: 

This is the string against which getty tries to match its second 
argument. It is often the speed, such as 1200, at which the ter- 
minal is supposed to run, but it need not be (see below). 

These flags are the initial ioctl(2) settings to which the terminal 
is to be set if a terminal type is not specified to getty. The flags 
that getty understands are the same as the ones listed in 
/usr/include/sys/termio.h (see termioO )). Normally only the 
speed flag is required in the initial-flags . Getty automatically 
sets the terminal to raw input mode and takes care of most of 
the other flags. The initial-flag settings remain in effect until 
getty executes login (.1). 

final-flags These flags take the same values as the initial-flags and are set 
just prior to getty executes login. The speed flag is again 
required. The composite flag SANE takes care of most of the 
other flags that need to be set so that the processor and terminal 
are communicating in a rational fashion. The other two com- 
monly specified final-flags are TAB3, so that tabs are sent to the 
terminal as spaces, and HUPCL, so that the line is hung up on 
the final close. 

login-prompt This entire field is printed as the login-prompt. Unlike the 
above fields where white space is ignored (a space, tab or new- 
line), they are included in the login-prompt field. 

next-label If this entry does not specify the desired speed, indicated by the 
user typing a <break> character, then getty will search for the 
entry with next-label as its label field and set up the terminal 
for those settings. Usually, a series of speeds are linked together 
in this fashion, into a closed set; For instance, 2400 linked to 
1200, which in turn is linked to 300, which finally is linked to 
2400. 

If getty is called without a second argument, then the first entry of 
/etc/gettydefs is used, thus making the first entry of /etc/gettydefs the default 
entry. It is also used if getty can not find the specified label. If /etc/gettydefs 
itself is missing, there is one entry built into the command which will bring up 
a terminal at 300 baud. 

It is strongly recommended that after making or modifying /etc/gettydefs, it be 
run through getty with the check option to be sure there are no errors. 


label 

initial-flags 
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FILES 

/etc/gettydefs 

SEE ALSO 

ioctl (2) . 

getty(lM), termio(7) in the 3B2 Computer System Administration Utilities 
Guide. 

login (1) in the 3B2 Computer System User Reference Manual. 
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NAME 

gps - graphical primitive string, format of graphical files 

DESCRIPTION 

GPS is a format used to store graphical data. Several routines have been 

developed to edit and display GPS files on various devices. Also, higher level 

graphics programs such as plot (in stat ( 1 G) ) and vtoc (in roc(lG)) produce 

GPS format output files. 

A GPS is composed of five types of graphical data or primitives. 

GPS PRIMITIVES 

lines The lines primitive has a variable number of points from which zero 

or more connected line segments are produced. The first point 
given produces a move to that location. (A move is a relocation of 
the graphic cursor without drawing.) Successive points produce line 
segments from the previous point. Parameters are available to set 
color, weight, and style (see below). 

arc The arc primitive has a variable number of points to which a curve 

is fit. The first point produces a move to that point. If only two 
points are included, a line connecting the points will result; if three 
points a circular arc through the points is drawn; and if more than 
three, lines connect the points. (In the future, a spline will be fit to 
the points if they number greater than three.) Parameters are 
available to set color, weight, and style. 

text The text primitive draws characters. It requires a single point 

which locates the center of the first character to be drawn. Param- 
eters are color, font, textsize, and textangle. 

hardware The hardware primitive draws hardware characters or gives control 
commands to a hardware device. A single point locates the begin- 
ning location of the hardware string. 

comment A comment is an integer string that is included in a GPS file but 
causes nothing to be displayed. All GPS files begin with a comment 
of zero length. 

GPS PARAMETERS 

color Color is an integer value set for arc, lines, and text primitives. 

weight Weight is an integer value set for arc and lines primitives to indi- 
cate line thickness. The value 0 is narrow weight, 1 is bold, and 2 
is medium weight. 

style Style is an integer value set for lines and arc primitives to give one 
of the five different line styles that can be drawn on TEKTRONIX 
4010 series storage tubes. They are: 

0 solid 

1 dotted 

2 dot dashed 

3 dashed 

4 long dashed 

font An integer value set for text primitives to designate the text font to 

be used in drawing a character string. (Currently font is expressed 
as a four-bit weight value followed by a four-bit style value.) 

textsize Textsize is an integer value used in text primitives to express the 
size of the characters to be drawn. Textsize represents the height 
of characters in absolute universe-units and is stored at one-fifth 
this value in the size-orientation Go) word (see below) . 
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textangle Textangle is a signed integer value used in text primitives to express 

rotation of the character string around the beginning point. 

Textangle is expressed in degrees from the positive x-axis and can 
be a positive or negative value. It is stored in the size-orientation 
(so) word as a value 256/360 of it’s absolute value. 

ORGANIZATION 

GPS primitives are organized internally as follows: 


lines 

arc 

text 

hardware 

comment 

cw 


point (s) 


cw points sw 

cw points sw 
cw point sw so [string] 
cw point [string] 
cw [string] 

Cw is the control word and begins all primitives. It consists of four 
bits that contain a primitive-type code and twelve bits that contain 
the word-count for that primitive. 

Point (s) is one or more pairs of integer coordinates. Text and 
hardware primitives only require a single point. Point (s) are values 
within a Cartesian plane or universe having 64K (— 32K to +32K) 
points on each axis. 


sw Sw is the style-word and is used in lines, arc, and text primitives. 

For all three, eight bits contain color information. In arc and lines 
eight bits are divided as four bits weight and four bits style. In the 
text primitive eight bits of sw contain the font. 

so So is the size-orientation word used in text primitives. Eight bits 

contain text size and eight bits contain text rotation. 

string String is a null-terminated character string. If the string does not 
end on a word boundary, an additional null is added to the GPS file 
to insure word-boundary alignment. 


SEE ALSO 

graphics(lG), stat(lG), toc(lG) in the 3B2 Computer System Graphics Utili- 
ties Guide. 
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NAME 

group — group file 
DESCRIPTION 

Group contains for each group the following information: 

group name 
encrypted password 
numerical group ID 

comma-separated list of all users allowed in the group 

This is an ASCII file. The fields are separated by colons; each group is 
separated from the next by a new-line. If the password field is null, no pass- 
word is demanded. 

This file resides in directory /etc. Because of the encrypted passwords, it can 
and does have general read permission and can be used, for example, to map 
numerical group ID’s to names. 

FILES 

/etc/group 

SEE ALSO 

passwd(4). 

passwd(l) in the 3B2 Computer System User Reference Manual. 
newgrp(lM) in the 3B2 Computer System Administration Utilities Guide. 
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NAME 

inittab — script for the init process 
DESCRIPTION 

The inittab file supplies the script to init's role as a general process dispatcher. 
The process that constitutes the majority of init's process dispatching activities 
is the line process /etc/getty that initiates individual terminal lines. Other 
processes typically dispatched by init are daemons and the shell. 

The inittab file is composed of entries that are position dependent and have the 
following format: 

id:rstate:action:process 

Each entry is delimited by a newline, however, a backslash (\) preceding a 
newline indicates a continuation of the entry. Up to 512 characters per entry 
are permitted. Comments may be inserted in the process field using the sh(\) 
convention for comments. Comments for lines that spawn gettys are displayed 
by the who( 1) command. It is expected that they will contain some informa- 
tion about the line such as the location. There are no limits (other than max- 
imum entry size) imposed on the number of entries within the inittab file. The 
entry fields are: 

id This is one or two characters used to uniquely identify an entry. 

rstate This defines the run-level in which this entry is to be processed. 

Run-levels effectively correspond to a configuration of processes in the 
system. That is, each process spawned by init is assigned a run-level 
or run-levels in which it is allowed to exist. The run-levels are 
represented by a number ranging from 0 through 6. As an example, 
if the system is in run-level 1, only those entries having a 1 in the 
rstate field will be processed. When init is requested to change run- 
levels, all processes which do not have an entry in the rstate field for 
the target run-level will be sent the warning signal (SIGTERM) and 
allowed a 20-second grace period before being forcibly terminated by 
a kill signal (SIGKILL). The rstate field can define multiple run- 
levels for a process by selecting more than one run-level in any com- 
bination from 0—6. If no run-level is specified, then the process is 
assumed to be valid at all run-levels 0—6. There are three other 
values, a, b and c, which can appear in the rstate field, even though 
they are not true run-levels. Entries which have these characters in 
the rstate field are processed only when the telinit (see im'((lM)) pro- 
cess requests them to be run (regardless of the current run-level of 
the system). They differ from run-levels in that init can never enter 
run-level a, b or c. Also, a request for the execution of any of these 
processes does not change the current run-level. Furthermore, a pro- 
cess started by an a, b or c command is not killed when init changes 
levels. They are only killed if their line in /etc/inittab is marked off 
in the action field, their line is deleted entirely from /etc/inittab, or 
init goes into the SINGLE USER state. 

action Key words in this field tell init how to treat the process specified in 
the process field. The actions recognized by init are as follows: 

respawn If the process does not exist then start the process, do not 
wait for its termination (continue scanning the inittab 
file), and when it dies restart the process. If the process 
currently exists then do nothing and continue scanning 
the inittab file. 
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wait 

once 

boot 

bootwait 

powerfail 

powerwait 

off 

ondemand 

initdefault 


Upon init’s entering the run-level that matches the 
entry’s r state, start the process and wait for its termina- 
tion. All subsequent reads of the inittab file while init is 
in the same run-level will cause init to ignore this entry. 

Upon init's entering a run-level that matches the entry’s 
rstate, start the process, do not wait for its termination. 
When it dies, do not restart the process. If upon entering 
a new run-level, where the process is still running from a 
previous run-level change, the program will not be res- 
tarted. 

The entry is to be processed only at init's boot-time read 
of the inittab file. Init is to start the process, not wait for 
its termination; and when it dies, not restart the process. 
In order for this instruction to be meaningful, the rstate 
should be the default or it must match init's run-level at 
boot time. This action is useful for an initialization func- 
tion following a hardware reboot of the system. 

The entry is to be processed only at init’s boot-time read 
of the inittab file. Init is to start the process, wait for its 
termination and, when it dies, not restart the process. 

Execute the process associated with this entry only when 
init receives a power fail signal (SIGPWR see signal (2)). 

Execute the process associated with this entry only when 
init receives a power fail signal (SIGPWR) and wait until 
it terminates before continuing any processing of inittab. 

If the process associated with this entry is currently run- 
ning, send the warning signal (SIGTERM) and wait 20 
seconds before forcibly terminating the process via the kill 
signal (SIGKILL). If the process is nonexistent, ignore the 
entry. 

This instruction is really a synonym for the respawn 
action. It is functionally identical to respawn but is given 
a different keyword in order to divorce its association with 
run-levels. This is used only with the a, b or c values 
described in the rstate field. 

An entry with this action is only scanned when init ini- 
tially invoked. Init uses this entry, if it exists, to deter- 
mine which run-level to enter initially. It does this by 
taking the highest run-level specified in the rstate field 
and using that as its initial state. If the rstate field is 
empty, this is interpreted as 0123456 and so init will 
enter run-level 6. Also, the initdefault entry cannot 
specify that init start in the SINGLE USER state. Addi- 
tionally, if init does not find an initdefault entry in 
/etc/inittab, then it will request an initial run-level from 
the user at reboot time. 
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sysinit Entries of this type are executed before init tries to access 
the console. It is expected that this entry will be only 
used to initialize devices on which init might try to ask 
the run-level question. These entries are executed and 
waited for before continuing. 

process This is a sh command to be executed. The entire process field is 
prefixed with exec and passed to a forked sh as sh — c 'exec com- 
mand'. For this reason, any legal sh syntax can appear in the process 
field. Comments can be inserted with the ; #comment syntax. 

FILES 

/etc/inittab 
SEE ALSO 

exec (2), open (2), signal (2). 

getty(lM), init(lM) in the 3B2 Computer System Administration Utilities 

Guide. 

sh(l), who(l) in the 3B2 Computer System User Reference Manual. 
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NAME 

inode — format of an i-node 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ino.h> 

DESCRIPTION 

An i-node for a plain file or directory in a file system has the following struc- 
ture defined by <sys/ino.h>. 

/* Inode structure as it appears on a disk block. */ 


struct dinode 

f 



l 

ushort 

dijnode; 

/* mode and type of file */ 

short 

dinlink; 

/* number of links to file */ 

ushort 

diuid; 

/» owner’s user id »/ 

ushort 

dijgid; 

/* owner’s group id */ 

offt 

di_size; 

/* number of bytes in file */ 

char 

di_addr[40l; 

/* disk block addresses */ 

timet 

diatime; 

/* time last accessed */ 

time t 

di mtime; 

/* time last modified */ 

timet 

dictime; 

/* time of last file status change */ 


}; 

/* 

* the 40 address bytes: 

* 39 used; 13 addresses 

* of 3 bytes each. 

*/ 

For the meaning of the defined types offj and time t see types (.5). 

FILES 

/usr/include/sys/ino.h 
SEE ALSO 

stat(2), fs(4), types (5). 
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NAME 

issue — issue identification file 
DESCRIPTION 

The file /etc/issue contains the issue or project identification to be printed as a 
login prompt. This is an ASCII file which is read by program getty and then 
written to any terminal spawned or respawned from the lines file. 

FILES 

/etc/issue 
SEE ALSO 

login ( 1 ) in the 3B2 Computer System User Reference Manual. 
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NAME 

ldfcn — common object file access routines 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

DESCRIPTION 

The common object file access routines are a collection of functions for reading 
an object file that is in computer (common) object file form. Although the cal- 
ling program must know the detailed structure of the parts of the object file 
that it processes, the routines effectively insulate the calling program from 
knowledge of the overall structure of the object file. 

The interface between the calling program and the object file access routines is 
based on the defined type LDFILE, defined as struct ldfile, declared in the 
header file ldfcn.h. The primary purpose of this structure is to provide uniform 
access to both simple object files and to object files that are members of an 
archive file. 

The function Idopeni 3X) allocates and initializes the LDFILE structure and 
returns a pointer to the structure to the calling program. The fields of the 
LDFILE structure may be accessed individually through macros defined in 
ldfcn.h and contain the following information: 

LDFILE *ldptr; 

TYPE(ldptr) The file magic number used to distinguish between archive 
members and simple object files. 

IOPTR(ldptr) The file pointer returned by fopen and used by the standard 
input/output functions. 

OFFSET(ldptr) The file address of the beginning of the object file; the offset is 
non-zero if the object file is a member of an archive file. 

HEADER (ldptr) The file header structure of the object file. 

The object file access functions themselves may be divided into four categories: 

(1) functions that open or close an object file 

Idopeni 3X) and Idopeni 3X) 

open a common object file 
Idclosei. 3X) and Idclose (3X) 

close a common object file 

(2) functions that read header or symbol table information 

Idahread (3X) 

read the archive header of a member of an archive file 
Idfhread (3X) 

read the file header of a common object file 
ldshread(3X ) and Idshread (3X) 

read a section header of a common object file 
Idtbread (3X) 

read a symbol table entry of a common object file 
Idgetname (3X) 

retrieve a symbol name from a symbol table entry or 
from the string table 

(3) functions that position an object file at (seek to) the start of the 
section, relocation, or line number information for a particular section. 
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Idohseek (3X) 

seek to the optional file header of a common object file 
IdsseekOX ) and Idsseek (3X) 

seek to a section of a common object file 
Idrseeki. 3X) and Idrseek(JX) 

seek to the relocation information for a section of a 
common object file 
Idlseek (3X) and IdlseekOX) 

seek to the line number information for a section of a 
common object file 
Idtbseek (3X) 

seek to the symbol table of a common object file 

(4) the function Idtbindexf, 3X) which returns the index of a particular 
common object file symbol table entry. 

These functions are described in detail on their respective manual pages. 

All the functions except ldopen( 3X), ldgetname(3X ) , IdopendX) , and 
ldtbindex{ 3X) return either SUCCESS or FAILURE, both constants defined in 
ldfcn.h. Ldopeni 3X) and Idopen (3X) both return pointers to an LDFILE struc- 
ture. 

Additional access to an object file is provided through a set of macros defined 
in ldfcn.h. These macros parallel the standard input/output file reading and 
manipulating functions, translating a reference of the LDFILE structure into a 
reference to its file descriptor field. 

The following macros are provided: 

GETC(ldptr) 

FGETC(ldptr) 

GETW(ldptr) 

UNGETC (c, ldptr) 

FGETSfs, n, ldptr) 

FREAD((char *) ptr, sizeof (*ptr), nitems, ldptr) 

FSEEK (ldptr, offset, ptrname) 

FTELL (ldptr) 

REWIND(ldptr) 

FEOF(ldptr) 

FERROR(ldptr) 

FILENO(ldptr) 

SETBUFOdptr, buf) 

STROFFSET (ldptr) 

The STROFFSET macro calculates the address of the string table in a UNIX 
system release 5.0 object file. See the manual entries for the corresponding 
standard input/output library functions for details on the use of the rest of the 
macros. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

fseek(3S), ldahread(3X), ldclose(3X), ldgetname(3X), ldfhread(3X), 
ldlread(3X), ldlseek(3X), ldohseek(3X), ldopen(3X), ldrseek(3X), ldlseek(3X), 
ldshread(3X), ldtbindex(3X), ldtbread(3X), ldtbseek(3X), intro(5). 

WARNING 

The macro FSEEK defined in the header file ldfcn.h translates into a call to the 
standard input/output function fseekOS). FSEEK should not be used to seek 
from the end of an archive file since the end of an archive file may not be the 
same as the end of one of its object file members! 
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NAME 

linenum — line number entries in a common object file 
SYNOPSIS 

#include <linenum.h> 


DESCRIPTION 

Compilers based on pcc generate an entry in the object file for each C source 
line on which a breakpoint is possible (when invoked with the — g option; see 
cc(l)). Users can then reference line numbers when using the appropriate 
software test system (see sdb( 1)). The structure of these line number entries 
appears below. 


struct lineno 

( 


union 

{ 


long 

long 

} 

unsigned short 


lsymndx ; 
l_paddr ; 
laddr ; 
ljnno ; 


Numbering starts with one for each function. The initial line number entry for 
a function has llnno equal to zero, and the symbol table index of the function’s 
entry is in Ijymndx. Otherwise, l lnno is non-zero, and / _paddr is the physi- 
cal address of the code for the referenced line. Thus the overall structure is the 
following: 


laddr 

ljnno 

function symtab index 

0 

physical address 

line 

physical address 

line 

function symtab index 

0 

physical address 

line 

physical address 

line 


SEE ALSO 

a.out(4). 

cc(l) in the 3B2 Computer System C Programming Language Utilities. 
sdb(l) in the 3B2 Computer System Extended Software Generation System 
Utilities. 


10/84 


- 1 - 


10/84 



MASTER (4) 


MASTER (4) 


NAME 

master — master configuration database 
DESCRIPTION 

The master configuration database is a collection of files. Each file contains 
configuration information for a device or module that may be included in the 
system. A file is named with the module name to which it applies. This collec- 
tion of files is maintained in a directory called /etc/master.d. Each individual 
file has an identical format. For convenience, this collection of files will be 
referred to as the master file, as though it was a single file. This will allow a 
reference to the master file to be understood to mean the individual file in the 
master.d directory that corresponds to the name of a device or module. The file 
is used by the mkboot{ 1M) program to obtain device information to generate 
the device driver and configurable module files. It is also used by the 
sysdefi, 1M) program to obtain the names of supported devices. Master consists 
of two parts; they are separated by a line with a dollar sign ($) in column 1. 
Part 1 contains device information for both hardware and software devices, and 
loadable modules. Part 2 contains parameter declarations used in part 1 . Any 
line with an asterisk (*) in column 1 is treated as a comment. 


Part 1, Description 

Hardware devices, software drivers and loadable modules are defined with a 
line containing the following information. Field 1 must begin in the left most 
position on the line. Fields are separated by white space (tab or blank). 


Field 1: 


Field 2: 

Field 3: 
Field 4: 

Field 5: 
Field 6: 
Field 7: 


element characterisitics: 
o specify only once 

r required device 

b block device 

c character device 

a generate segment descriptor array 

t initialize cdevsw[].d_ttys 

s software driver 

x not a driver; a loadable module 

number The first interrupt vector for an integral 

device 

number of interrupt vectors required by a hardware dev- 
ice: " if none. 

handler prefix (4 chars, maximum) 

software driver external major number; " if not a 
software driver 

number of sub-devices per device; " if none 
interrupt priority level of the device; " if none 
dependency list (optional); this is a comma separated list 
of other drivers or modules that must be present in the 
configuration if this module is to be included 


For each module, two classes of information are required by 
mkbooti 1M): external routine references and variable definitions. 
Routine and variable definition lines begin with white space and 
immediately follow the initial module specification line. These lines are 
free form, thus they may be continued arbitrarily between non-blank 
tokens as long as the first character of a line is white space. 


Part 1, Routine Reference Lines 

If the UNIX system kernel or other dependent module contains external refer- 
ences to a module, but the module is not configured, then these external refer- 
ences would be undefined. Therefore, the routine reference lines are used to 
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provide the information necessary to generate appropriate dummy functions at 
boot time when the driver is not loaded. 

Routine references are defined as follows: 

Field 1: routine name 0 

Field 2: the routine type: one of 

{} routine_name(){} 

{nosys} routine nameO (return nosysO;} 

(nodev) routine nameO (return nodevO;} 

(false) routine nameO (return 0;) 

(true) routine_nameO (return 1;) 

Part 1, Variable Definition Lines 

Variable definition lines are used to generate all variables required by the 
module. The variable generated may be of arbitrary size, be initialized or not, 
or be arrays containing an arbitrary number of elements. 
variable references are defined as follows: 

Field 1 : variablename 

Field 2: [ expr ] — optional field used to indicate array size 

Field 3: (length) — required field indicating the size of the vari- 

able 

Field 4: ={ expr,... ) — optional field used to initialize individual 

elements of a variable 

The length field is mandatory. It is an arbitrary sequence of length specifiers, 
each of which may be one of the following: 

%i an integer 

%1 a long integer 

%s a short integer 

%c a single character 

%number a field which is number bytes long 

%number c a character string which is number bytes long 

For example, the length field 

( %8c %1 %Ox58 %1 %c %c ) 

could be used to identify a variable consistring of a character sting 8-bytes 
long, a long integer, a 0x58 byte structure of any type, another long integer, 
and two characters. Appropriate alignment of each % specification is per- 
formed (%number is word aligned) and the variable length is rounded up to the 
next word boundary during processing. 

The expressions for the optional array size and initialization are infix expres- 
sions consisting of the usual operators for addition, subtraction, multiplication, 
and division: +, — , *, and /. Multiplication and division have the higher pre- 
cedence, but parentheses may be used to override the default order. The buil- 
tin functions min and max accept a pair of expressions, and return the 
appropriate value. The operands of the expression may be any mixture of the 
following: 

&name address of name where name is any symbol defined by 
the kernel, any module loaded or any variable definition 
line of any module loaded 

#name sizeof name where name is any variable name defined by 
a variable definition for any module loaded; the size is 
that of the individual variable— not the size of an entire 
array 
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#c 

#C(name) 

#D 

#D(name) 

#M 

#M(name) 

name 

number 

string 


number of controllers present; this number is determined 
by the EDT for hardware devices, or by the number pro- 
vided in the system file for non-hardware drivers or 
modules 

number of controllers present for the module name ; this 
number is determined by the EDT for hardware devices, 
or by the number provided in the system file for non- 
hardware drivers or modules 

number of devices per controller taken directly from the 
current master file entry 

number of devices per controller taken directly from the 
master file entry for the module name 
the internal major number assigned to the current 
module if it is a device driver; zero of this module is not 
a device driver 

the internal major number assigned to the module name 
if it is a device driver: zero if that module is not a device 
driver 

value of a parameter as defined in the second part of 
master 

arbitrary number (octal, decimal, or hex allowed) 
a character string enclosed within double quotes (all of 
the character string conventions supported by the C 
language are allowed); this operand has a value which is 
the address of a character array containing the specified 
string 


When initializing a variable, one initialization expression should be provided for 
each %i, %1, %s, or %c of the length field. The only initializers allowed for a 
‘%number c’ are either a character string (the string may not be longer than 
number), or an explicit zero. Initialization expressions must be separated by 
commas, and variable initialization will proceed element by element. Note that 
%number specification cannot be initialized— they are set to zero. Only the first 
element of an array can be initialized, the other elements are set to zero. If 
there are more initializers than size specifications, it is an error and execution 
of the mkbootl 1M) program will be aborted. If there are fewer initializations 
than size specifications, zeros will be used to pad the variable. For example: 

={ "V2.L1", #C*#D, max(10,#D), #C(OTHER), #M (OTHER) } 

would be a possible initialization of the variable whose length field was given in 
the preceeding example. 

Part 2, Description 

Parameter declarations may be used to define a value symbolically. Values can 
be associated with identifiers and these identifiers may be used in the variable 
definition lines. 

Parameters are defined as follows: 

Field 1 : identifier (8 characters maximum) 

Field 2: 

Field 3: value, the value may be a number (decimal, octal, or hex 

allowed), or a string 
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EXAMPLE 

A sample master file for a tty device driver would be named "atty" if the device 
appeared in the EDT as "ATTY". The driver is a character device, the driver 
prefix is at, two interrupt vectors are used, and the interrupt priority is 6. In 
addition, another driver named "ATLOG" is necessary for the correct operation 
of the software associated with this device. 

♦FLAG ffVEC PREFIX SOFT If DEV IPL DEPENDENCIES/ VARIABLES 
tea 2 at - 2 6 ATLOG 

atpoint ( ) {false) 
at_tty [ If C*#D ] (%0x58) 
at_cnt(Si) ={ ffC^ffD ) 
at_logma j ( %i ) =( if M ( ATLOG ) } 
at_id ( %8 c ) ={ ATID ) 
at_table (%i%l%31%s) 

= { max ( # C , ATMAX ) , 

£at_tty , 

(1C ) 

$ 

ATID = "fred" 

ATMAX = 6 

This master file will cause a routine named atpoint to be generated by the boot 
program if the ATTY driver is not loaded, and there is a reference to this rou- 
tine from any other module loaded. When the driver is loaded, the variables 
atjty, at cnt , atjogmaj, at id, and at table will be allocated and initialized 
as specified. Due to the t flag, the djlys field in the character device switch 
table will be initialized to point to at_tty (the first variable definition line con- 
tains the variable whose address will be stored in dttys). The ATTY driver 
would reference these variables by coding: 

extern struct tty at_tty[ ]; 
extern int at_cnt; 
extern int atjogmaj; 
extern char at_id[8]; 
extern struct { 

int member 1; 
struct tty *member2; 
char junkt 31]; 
short member3; 

) atjable; 


FILES 

/etc/master.d/* 

SEE ALSO 

boothdr(4), system (4). 

mkboot(lM), sysdef(lM) in the 3B2 Computer System Administration Utili- 
ties Guide. 
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NAME 

mnttab — mounted file system table 
SYNOPSIS 

#include <mnttab.h> 


DESCRIPTION 

Mnttab resides in directory /etc and contains a table of devices, mounted by 
the mount (1M) command, in the following structure as defined by 

<mnttab.h> : 

struct mnttab { 

char mt_dev[32]; 

char mt_filsys[32]; 

short mt_ro_flg; 

timet mttime; 

); 

Each entry is 70 bytes in length; the first 32 bytes are the null-padded name of 
the place where the special file is mounted; the next 32 bytes represent the 
null-padded root name of the mounted special file; the remaining 6 bytes con- 
tain the mounted special file's read/write permissions and the date on which it 
was mounted. 

The maximum number of entries in mnttab is based on the system parameter 
NMOUNT located in /usr/src/uts/cf/conf.c, which defines the number of allow- 
able mounted special files. 

SEE ALSO 

mount (1M), setmnt(lM) in the 3B2 Computer System Administration Utili- 
ties Guide. 
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NAME 

passwd — password file 
DESCRIPTION 

Passwd contains for each user the following information: 

login name 
encrypted password 
numerical user ID 
numerical group ID 

GCOS job number, box number, optional GCOS user ID 
initial working directory 
program to use as shell 

This is an ASCII file. Each field within each user’s entry is separated from the 
next by a colon. The GCOS field is used only when communicating with that 
system, and in other installations can contain any desired information. Each 
user is separated from the next by a new-line. If the password field is null, no 
password is demanded; if the shell field is null, the shell itself is used. 

This file resides in directory /etc. Because of the encrypted passwords, it can 
and does have general read permission and can be used, for example, to map 
numerical user IDs to names. 

The encrypted password consists of 13 characters chosen from a 64-character 
alphabet (., /, 0—9, A— Z, a— z), except when the password is null, in which 
case the encrypted password is also null. Password aging is effected for a par- 
ticular user if his encrypted password in the password file is followed by a 
comma and a non-null string of characters from the above alphabet. (Such a 
string must be introduced in the first instance by the super-user.) 

The first character of the age, M say, denotes the maximum number of weeks 
for which a password is valid. A user who attempts to login after his password 
has expired will be forced to supply a new one. The next character, m say, 
denotes the minimum period in weeks which must expire before the password 
may be changed. The remaining characters define the week (counted from the 
beginning of 1970) when the password was last changed. (A null string is 
equivalent to zero.) M and m have numerical values in the range 0—63 that 
correspond to the 64-character alphabet shown above (i.e., / = 1 week; z = 63 
weeks) . If m = M = 0 (derived from the string . or ..) the user will be forced 
to change his password the next time he logs in (and the “age” will disappear 
from his entry in the password file). If m > M (signified, e.g., by the string 
./) only the super-user will be able to change the password. 

FILES 

/etc/passwd 
SEE ALSO 

a641(3C), getpwent(3C), group(4). 

login (1), passwd (1) in the 3B2 Computer System User Reference Manual. 
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NAME 

plot — graphics interface 

DESCRIPTION 

Files of this format are produced by routines described in plot OX) and are 
interpreted for various devices by commands described in tplot (1G). A graph- 
ics file is a stream of plotting instructions. Each instruction consists of an 
ASCII letter usually followed by bytes of binary information. The instructions 
are executed in order. A point is designated by four bytes representing the x 
and y values; each value is a signed integer. The last designated point in an 1, 
m, n, or p instruction becomes the “current point” for the next instruction. 

Each of the following descriptions begins with the name of the corresponding 
routine in plotOX). 

m move; The next four bytes give a new current point. 

n cont: Draw a line from the current point to the point given by the next four 
bytes. See tplot ( 1G). 

p point: Plot the point given by the next four bytes. 

I line: Draw a line from the point given by the next four bytes to the point 
given by the following four bytes. 

t label: Place the following ASCII string so that its first character falls on the 
current point. The string is terminated by a new-line. 

e erase: Start another frame of output. 

f linemod: Take the following string, up to a new-line, as the style for draw- 
ing further lines. The styles are “dotted”, “solid”, “longdashed”, “short- 
dashed”, and “dotdashed”. Effective only for the — T4014 and —Tver 
options of tploti 1G) (TEKTRONIX 4014 terminal and Versatec plotter). 

s space: The next four bytes give the lower left corner of the plotting area; 
the following four give the upper right corner. The plot will be magnified or 
reduced to fit the device as closely as possible. 

Space settings that exactly fill the plotting area with unity scaling appear below 
for devices supported by the filters of tplot (1G). The upper limit is just outside 
the plotting area. In every case the plotting area is taken to be square; points 
outside may be displayable on devices whose face is not square. 

DASI 300 space(0, 0, 4096, 4096); 

DASI 300s space(0, 0, 4096, 4096); 

DASI 450 space(0, 0, 4096, 4096); 

TEKTRONIX 4014 space(0, 0, 3120, 3120); 

Versatec plotter space(0, 0, 2048, 2048); 

SEE ALSO 

plot(3X), gps(4), term (5). 

graph(lG), tplot(lG) in the 3B2 Computer System Graphics Utilities Guide. 
WARNING 

The plotting library plotOX) and the curses library curses OX) both use the 
names eraseO and moveO. The curses versions are macros. If you need both 
libraries, put the plotOX) code in a different source file than the curses OX) 
code, and/or #undef moveO and eraseO in the plotOX ) code. 
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NAME 

pnch — file format for card images 
DESCRIPTION 

The PNCH format is a convenient representation for files consisting of card 
images in an arbitrary code. 

A PNCH file is a simple concatenation of card records. A card record consists 
of a single control byte followed by a variable number of data bytes. The con- 
trol byte specifies the number (which must lie in the range 0-80) of data bytes 
that follow. The data bytes are 8-bit codes that constitute the card image. If 
there are fewer than 80 data bytes, it is understood that the remainder of the 
card image consists of trailing blanks. 
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NAME 

profile — system-wide user profile 

SYNOPSIS 

/etc /profile 

DESCRIPTION 

All user who have the shell, sMl), as their login command have the commands 
in this file included as part of the login sequence. It allows the system adminis- 
trator to perform services for the entire user community. Typical services are 
the announcement of system news, user mail, and the setting of default environ- 
mental variables. 

It is not unusual to have special actions for the root login or the ju( 1) com- 
mand. 

FILES 

The file /etc/TIMEZONE is included early in the file to establish the default 
time zone. 

SEE ALSO 

timezone(4). 

sh ( 1 ) in the 3B2 Computer System User Reference Manual. 
su(lM) in the 3B2 Computer System Administration Utilities Guide. 

BUGS 

Care must be taken in providing system-wide services. One user’s service is 
another’s annoyance. Personal ''.profile" files are better for serving all but the 
most global needs. 
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NAME 

reloc — relocation information for a common object file 

SYNOPSIS 

#include <reloc.h> 

DESCRIPTION 

Object files have one relocation entry for each relocatable reference in the text 
or data. If relocation information is present, it will be in the following format. 

struct reloc 

{ 

long rvaddr ; /* (virtual) address of reference »/ 

long r_symndx ; /* index into symbol table */ 

short rtype ; /* relocation type «/ 

) ; 
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NAME 

sccsfile — format of SCCS file 
DESCRIPTION 

An SCCS file is an ASCII file. It consists of six logical parts: the checksum , 
the delta table (contains information about each delta), user names (contains 
login names and/or numerical group IDs of users who may add deltas), flags 
(contains definitions of internal keywords), comments (contains arbitrary 
descriptive information about the file), and the body (contains the actual text 
lines intermixed with control lines). 

Throughout an SCCS file there are lines which begin with the ASCII SOH (start 
of heading) character (octal 001). This character is hereafter referred to as 
the control character and will be represented graphically as @. Any line 
described below which is not depicted as beginning with the control character is 
prevented from beginning with the control character. 

Entries of the form DDDDD represent a five-digit string (a number between 
00000 and 99999). 

Each logical part of an SCCS file is described in detail below. 

Checksum 

The checksum is the first line of an SCCS file. The form of the line is: 

@hDDDDD 

The value of the checksum is the sum of all characters, except those of 
the first line. The @h provides a magic number of (octal) 064001. 

Delta table 

The delta table consists of a variable number of entries of the form: 

@s DDDDD/ DDDDD/ DDDDD 

@d <type> <SCCSID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 
@i DDDDD ... 

@x DDDDD ... 

@g DDDDD ... 

@m <MR number> 


@c <comments> ... 


@e 

The first line (@s) contains the number of lines 
inserted/deleted/unchanged, respectively. The second line (@d) con- 
tains the type of the delta (currently, normal: D, and removed: R), the 
SCCS ID of the delta, the date and time of creation of the delta, the 
login name corresponding to the real user ID at the time the delta was 
created, and the serial numbers of the delta and its predecessor, respec- 
tively. 

The @i, @x, and @g lines contain the serial numbers of deltas 
included, excluded, and ignored, respectively. These lines are optional. 

The @m lines (optional) each contain one MR number associated with 
the delta; the @c lines contain comments associated with the delta. 
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The @e line ends the delta table entry. 

User names 

The list of login names and/or numerical group IDs of users who may 
add deltas to the file, separated by new-lines. The lines containing 
these login names and/or numerical group IDs are surrounded by the 
bracketing lines @u and @U. An empty list allows anyone to make a 
delta. Any line starting with a ! prohibits the succeeding group or user 
from making deltas. 

Flags 

Keywords used internally (see admini 1) for more information on their 
use). Each flag line takes the form: 

@f <flag> <optional text> 

The following flags are defined: 

@f t <type of program > 

@f v < program name> 

@f i <keyword string> 

@f b 

@f m < module name> 

@f f <floor> 

@f c <ceiling> 

@f d <default-sid> 

@f n 
@f j 

@f 1 < lock-releases > 

@f q <user defined> 

@f z < reserved for use in interfaces> 

The t flag defines the replacement for the %Y% identification keyword. 
The v flag controls prompting for MR numbers in addition to com- 
ments; if the optional text is present it defines an MR number validity 
checking program. The i flag controls the warning/error aspect of the 
“No id keywords” message. When the i flag is not present, this mes- 
sage is only a warning; when the i flag is present, this message will 
cause a “fatal” error (the file will not be gotten, or the delta will not 
be made). When the b flag is present the — b keyletter may be used 
on the get command to cause a branch in the delta tree. The m flag 
defines the first choice for the replacement text of the %M% 
identification keyword. The f flag defines the “floor” release; the 
release below which no deltas may be added. The c flag defines the 
“ceiling” release; the release above which no deltas may be added. 
The d flag defines the default SID to be used when none is specified on 
a get command. The n flag causes delta to insert a “null” delta (a 
delta that applies no changes) in those releases that are skipped when 
a delta is made in a new release (e.g., when delta 5.1 is made after 
delta 2.7, releases 3 and 4 are skipped). The absence of the n flag 
causes skipped releases to be completely empty. The j flag causes get 
to allow concurrent edits of the same base SID. The 1 flag defines a list 
of releases that are locked against editing (ge?(l) with the -e 
keyletter). The q flag defines the replacement for the %Q% 
identification keyword. The z flag is used in certain specialized inter- 
face programs. 
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Comments 

Arbitrary text is surrounded by the bracketing lines @t and @T. The 
comments section typically will contain a description of the file’s pur- 
pose. 

Body 

The body consists of text lines and control lines. Text lines do not 
begin with the control character, control lines do. There are three 
kinds of control lines: insert , delete , and end, represented by: 

@1 DDDDD 
@D DDDDD 
@E DDDDD 

respectively. The digit string is the serial number corresponding to the 
delta for the control line. 

SEE ALSO 

admin(l), delta ( 1 ) , get(l), prs(l) in the 3B2 Computer System Source Code 
Control System Utilities. 
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NAME 

scnhdr — section header for a common object file 
SYNOPSIS 

#include <scnbdr.h> 

DESCRIPTION 

Every common object file has a table of section headers to specify the layout of 
the data within the file. Each section within an object file has its own header. 
The C structure appears below. 

struct scnhdr 

( 

char snametSYMNMLEN]; /* section name */ 

long s_paddr; /» physical address */ 

long s vaddr; /* virtual address */ 

long s_size; /* section size */ 

long s_scnptr; /* file ptr to raw data */ 

long srelptr; /* file ptr to relocation */ 

long sjnnoptr; /* file ptr to line numbers »/ 

unsigned short s nreloc; /* # reloc entries »/ 

unsigned short s nlnno; /* # line number entries »/ 
long sflags; /« flags */ 

} ; 

File pointers are byte offsets into the file; they can be used as the offset in a 
call to f seek (3S). If a section is initialized, the file contains the actual bytes. 
An uninitialized section is somewhat different. It has a size, symbols defined in 
it, and symbols that refer to it. But it can have no relocation entries, line 
numbers, or data. Consequently, an uninitialized section has no raw data in the 
object file, and the values for s scnptr, s relptr, sjnnoptr, sjireloc, and 
sjilnno are zero. 

SEE ALSO 

fseek(3S), a.out(4). 

Id (1) in the 3B2 Computer System Software Generation System Utilities. 
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NAME 

syms — common object file symbol table format 

SYNOPSIS 

#include <syms.h> 

DESCRIPTION 

Common object files contain information to support symbolic software testing 
(see irfi(l)). Line number entries, linenuml 4), and extensive symbolic infor- 
mation permit testing at the C source level. Every object file’s symbol table is 
organized as shown below. 

File name 1. 

Function 1. 

Local symbols for function 1 . 

Function 2. 

Local symbols for function 2. 

Static externs for file 1 . 

File name 2. 

Function 1. 

Local symbols for function 1 . 

Function 2. 

Local symbols for function 2. 

Static externs for file 2. 


Defined global symbols. 

Undefined global symbols. 

The entry for a symbol is a fixed-length structure. The members of the struc- 
ture hold the name (null padded), its value, and other information. The C 
structure is given below. 

#define SYMNMLEN 8 

#define FILNMLEN 14 

struct syment 
{ 


union 

f 


/* 

all ways to get symbol name »/ 

l 

char 

_n_name[SYMNMLEN]; /* symbol name */ 

struct 

/ 




l 

long 

nzeroes; 

/» 

== 0L when in string table */ 

long 

_n_offset; 

/* 

location of name in table */ 

} _n_n; 




char 

1 n- 

*_n_nptr[2]; 

/* 

allows overlaying */ 

J _n, 
long 

nvalue; 

/* 

value of symbol */ 

short 

nscnum; 

/* 

section number »/ 

unsigned short 

n_type; 

h 

type and derived type «/ 

char 

n_sclass; 

/* 

storage class »/ 

char 

}; 

n_numaux; 

/* 

number of aux entries */ 

#define n name 

n.nname 
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#define n_zeroes _n._n_n._n_zeroes 
#define noffset _n._n_n._n_offset 
#define n nptr _n._n_nptr[l] 

Meaningful values and explanations for them are given in both syms.h and 
Common Object File Format. Anyone who needs to interpret the entries 
should seek more information in these sources. Some symbols require more 
information than a single entry; they are followed by auxiliary entries that are 
the same size as a symbol entry. The format follows. 

union auxent 

{ 

struct 

{ 

long x_tagndx; 

union 

{ 

struct 

{ 

unsigned short x lnno; 
unsigned short x size; 

} xlnsz; 
long x_fsize; 

} x_misc; 
union 
{ 

struct 

{ 

long xlnnoptr; 
long xendndx; 

) xfcn; 

struct 

{ 

unsigned short x_dimen[DIMNUIVl]; 

} x_ary; 

} x_fcnary; 

unsigned short x_tvndx; 

} xsym; 

struct 

{ 

char x_fname[FILNMLEN]; 

} x_file; 

struct 


long x_scnlen; 
unsigned short x nreloc; 
unsigned short x_nlinno; 
} xscn; 


struct 


long xtvfill; 

unsigned short x tvlen; 
unsigned short x_tvran[2]; 
] x_tv; 

}; 
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Indexes of symbol table entries begin at zero. 

SEE ALSO 

a.out(4), linenum(4). 

sdb(l) in the 3B2 Computer System Extended Software Generation System 
Utilities. 

WARNINGS 

On machines in which longs are equivalent to ints (3B20 computer, VAX), they 
are converted to ints in the compiler to minimize the complexity of the compiler 
code generator. Thus the information about which symbols are declared as 
longs and which, as ints, does not show up in the symbol table. 
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NAME 

system — system configuration information table 
DESCRIPTION 

This file is used by the boot program to obtain configuration information that 
cannot be obtained from the equipped device table (EDT) at system boot time. 
This file generally contains a list of software drivers to include in the load, the 
assignment of system devices such as pipedev and swapdev, as well as instruc- 
tions for manually overriding the drivers selected by the self-configuring boot 
process. 

The syntax of the system file is given below. The parser for the /etc/system 
file is case sensitive. All upper case strings in the syntax below should be upper 
case in the /etc/system file as well. Nonterminal symbols are enclosed in angle 
brackets "<>" while optional arguments are enclosed in square brackets "[]". 
Ellipses "..." indicate optional repetition of the argument for that line. 

<fname> ::= pathname 

<string> ::= driver file name from /boot or EDT entry name 
<device> ::= special device name | DEV (< major >,< minor >) 
<major> ::= <number> 

<minor> ::= <number> 

<number> ::= decimal, octal or hex literal 

The lines listed below may appear in any order. Blank lines may be inserted at 
any point. Comment lines must begin with an asterisk. Entries for EXCLUDE 
and INCLUDE are cumulative. For all other entries, the last line to appear in 
the file is used — any earlier entries are ignored. 

BOOT: <fname> 

specifies the kernel a.out file to be booted; if the file is 
fully resolved (such as that produced by the 
mkunix (1M) program) then all other lines in the ■sys- 
tem file have no effect. 

EXCLUDE: [ <string> ] ... 

specifies drivers to exclude from the load even if the 
device is found in the EDT. 

INCLUDE: [ <string>[(<number>)] ] ... 

specifies software drivers or loadable modules to be 
included in the load. This is necessary to include the 
drivers for software "devices". The optional < number > 
(parenthesis required) specifies the number of "devices" 
to be controlled by the driver (defaults to 1). This 
number corresponds to the builtin variable #c which 
may be referred to by expressions in part one of the 
/etc/master file. 

ROOTDEV: <device> 

identifies the device containing the root file system. 
SWAPDEV: <device> <number> <number> 

identifies the device to be used as swap space, the block 
number the swap space starts at, and the number of 
swap blocks available. 

PIPEDEV: < device > 

identifies the device to be used for pipe space. 

FILES 

/etc/system 
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SEE ALSO 

master (4). 

crash(lM), mkunix(lM), mkboot(lM) in the 3B2 Computer System Adminis- 
tration Utilities Guide. 
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NAME 

term — format of compiled term file. 

SYNOPSIS 

term 

DESCRIPTION 

Compiled terminfo descriptions are placed under the directory 
/usr/lib/terminfo. In order to avoid a linear search of a huge UNIX system 
directory, a two-level scheme is used: / usr/Iib/terminfo/c/name where name is 
the name of the terminal, and c is the first character of name. Thus, act4 can 
be found in the file /usr/Iib/terminfo/a/act4. Synonyms for the same terminal 
are implemented by multiple links to the same compiled file. 

The format has been chosen so that it will be the same on all hardware. An 8 
or more bit byte is assumed, but no assumptions about byte ordering or sign 
extension are made. 

The compiled file is created with the compile program, and read by the routine 
setupterm. Both of these pieces of software are part of curses ( 3X). The file is 
divided into six parts: the header, terminal names, boolean flags, numbers, 
strings, and string table. 

The header section begins the file. This section contains six short integers in 
the format described below. These integers are (1) the magic number (octal 
0432); (2) the size, in bytes, of the names section; (3) the number of bytes in 
the boolean section; (4) the number of short integers in the numbers section; 
(5) the number of offsets (short integers) in the strings section; (6) the size, in 
bytes, of the string table. 

Short integers are stored in two 8-bit bytes. The first byte contains the least 
significant 8 bits of the value, and the second byte contains the most significant 
8 bits. (Thus, the value represented is 256*second+first.) The value —1 is 
represented by 0377, 0377, other negative value are illegal. The —1 generally 
means that a capability is missing from this terminal. Note that this format 
corresponds to the hardware of the VAX and PDP-11. Machines where this 
does not correspond to the hardware read the integers as two bytes and com- 
pute the result. 

The terminal names section comes next. It contains the first line of the ter- 
minfo description, listing the various names for the terminal, separated by the ‘|’ 
character. The section is terminated with an ASCII NUL character. 

The boolean flags have one byte for each flag. This byte is either 0 or 1 as the 
flag is present or absent. The capabilities are in the same order as the file 
<term.h> . 

Between the boolean section and the number section, a null byte will be 
inserted, if necessary, to ensure that the number section begins on an even byte. 
All short integers are aligned on a short word boundary. 

The numbers section is similar to the flags section. Each capability takes up 
two bytes, and is stored as a short integer. If the value represented is —1, the 
capability is taken to be missing. 

The strings section is also similar. Each capability is stored as a short integer, 
in the format above. A value of —1 means the capability is missing. Other- 
wise, the value is taken as an offset from the beginning of the string table. 
Spec.ul characters in "X or \c notation are stored in their interpreted form, not 
the printing representation. Padding information $<nn> and parameter infor- 
mation %x are stored intact in uninterpreted form. 
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The final section is the string table. It contains all the values of string capabili- 
ties referenced in the string section. Each string is null terminated. 

Note that it is possible for setupterm to expect a different set of capabilities 
than are actually present in the file. Either the database may have been 
updated since setupterm has been recompiled (resulting in extra unrecognized 
entries in the file) or the program may have been recompiled more recently 
than the database was updated (resulting in missing entries). The routine 
setupterm must be prepared for both possibilities — this is why the numbers 
and sizes are included. Also, new capabilities must always be added at the end 
of the lists of boolean, number, and string capabilities. 

As an example, an octal dump of the description for the Microterm ACT 4 is 
included: 

microterm|act4|microterm act iv, 

cr=~M, cudl="J, ind=M, bel^G, am, cubl^H, 
ed='_, el="“, clear='L, cup=‘T%pl%c%p2%c, 
cols#80, lines#24, cufl=”X, cuul="Z, home="], 
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377 

\0 

\0 

002 
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\0 
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\0 
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\b 

\0 

377 
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\n 

\0 
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\0 
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\0 
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\0 
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Some limitations: total compiled entries cannot exceed 4096 bytes. The name 
field cannot exceed 128 bytes. 

FILES 

/usr/lib/terminfo/*/* compiled terminal capability data base 
SEE ALSO 

curses(3X), terminfo(4). 

3B2 Computer System Terminal Information Utilities Guide. 
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NAME 

terminfo — terminal capability data base 

SYNOPSIS 

/ usr/lib/ terminfo/*/* 

DESCRIPTION 

Terminfo is a data base describing terminals, used, e.g.,, by vz'(l) and 
curses (. 3X). Terminals are described in terminfo by giving a set of capabilities 
which they have, and by describing how operations are performed. Padding 
requirements and initialization sequences are included in terminfo. 

Entries in terminfo consist of a number of separated fields. White space 
after each Y is ignored. The first entry for each terminal gives the names 
which are known for the terminal, separated by ‘|’ characters. The first name 
given is the most common abbreviation for the terminal, the last name given 
should be a long name fully identifying the terminal, and all others are under- 
stood as synonyms for the terminal name. All names but the last should be in 
lower case and contain no blanks; the last name may well contain upper case 
and blanks for readability. 

Terminal names (except for the last, verbose entry) should be chosen using the 
following conventions. The particular piece of hardware making up the termi- 
nal should have a root name chosen, thus “hp2621”. This name should not 
contain hyphens, except that synonyms may be chosen that do not conflict with 
other names. Modes that the hardware can be in, or user preferences, should 
be indicated by appending a hyphen and an indicator of the mode. Thus, a 
vtlOO in 132 column mode would be vtlOO-w. The following suffixes should be 
used where possible: 


Suffix 

Meaning 

Example 

-w 

Wide mode (more than 80 columns) 

vtlOO-w 

-am 

With auto, margins (usually default) 

vtlOO-am 

-nam 

Without automatic margins 

vtlOO-nam 

-n 

Number of lines on the screen 

aaa-60 

-na 

No arrow keys (leave them in local) 

clOO-na 

-np 

Number of pages of memory 

cl00-4p 

-rv 

Reverse video 

clOO-rv 

CAPABILITIES 




The variable is the name by which the programmer (at the terminfo level) 
accesses the capability. The capname is the short name used in the text of the 
database, and is used by a person updating the database. The i.code is the two 
letter internal code used in the compiled database, and always corresponds to 
the old termcap capability name. 

Capability names have no hard length limit, but an informal limit of 5 charac- 
ters has been adopted to keep them short and to allow the tabs in the source 
file caps to line up nicely. Whenever possible, names are chosen to be the same 
as or similar to the ANSI X3. 64-1979 standard. Semantics are also intended 
to match those of the specification. 

(P) indicates that padding may be specified 

(G) indicates that the string is passed through tparm withparms as given 

(#/). 

(*) indicates that padding may be based on the number of lines affected 
(# ( .) indicates the z 1 * 1 parameter. 
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Variable 

Cap- 

I. 

Description 

Booleans 

name 

Code 


auto left margin. 

bw 

bw 

cubl wraps from column 0 to last column 

auto_right_margin. 

am 

am 

Terminal has automatic margins 

beehive_glitch. 

xsb 

xb 

Beehive (fl=escape, f2=ctrl C) 

ceol_standoutj>litch. 

xhp 

xs 

Standout not erased by overwriting (hp) 

eat_newline_glitch, 

xenl 

xn 

newline ignored after 80 cols (Concept) 

eraseoverstrike. 

eo 

eo 

Can erase overstrikes with a blank 

generictype, 

gn 

gn 

Generic line type (e.g.„ dialup, switch). 

hard_copy, 

he 

he 

Hardcopy terminal 

has_meta_key. 

km 

km 

Has a meta key (shift, sets parity bit) 

hasstatusline. 

hs 

hs 

Has extra "status line" 

insert_null_glitch. 

in 

in 

Insert mode distinguishes nulls 

memory above, 

da 

da 

Display may be retained above the screen 

memorybelow. 

db 

db 

Display may be retained below the screen 

move_insert_mode. 

mir 

mi 

Safe to move while in insert mode 

movestandoutmode. 

msgr 

ms 

Safe to move in standout modes 

over_strike. 

os 

os 

Terminal overstrikes 

statuslineescok, 

eslok 

es 

Escape can be used on the status line 

teleray j»litch, 

xt 

xt 

Tabs ruin, magic so char (Teleray 1061) 

tildej>litch. 

hz 

hz 

Hazeltine; can not print ”’s 

transparentunderline, 

ul 

ul 

underline character overstrikes 

xonxoff. 

xon 

xo 

Terminal uses xon/xoff handshaking 

Numbers: 

columns. 

cols 

CO 

Number of columns in a line 

init_tabs, 

it 

it 

Tabs initially every # spaces 

lines. 

lines 

li 

Number of lines on screen or page 

linesofmemory. 

1m 

lm 

Lines of memory if > lines. 0 means varies 

magic_cookie_glitch. 

xmc 

sg 

Number of blank chars left by smso or rmso 

paddingbaudrate, 

pb 

pb 

Lowest baud where cr/nl padding is needed 

virtualterminal, 

vt 

vt 

Virtual terminal number (UNIX system) 

widthstatusline, 

wsl 

ws 

No. columns in status line 

Strings: 

back tab. 

cbt 

bt 

Back tab (P) 

bell, 

bel 

bl 

Audible signal (bell) (P) 

carriagereturn, 

cr 

cr 

Carriage return (P*) 

changescrollregion, 

csr 

cs 

change to lines #1 through #2 (vtlOO) (PG) 

clear_all_tabs, 

tbc 

ct 

Clear all tab stops (P) 

clearscreen, 

clear 

cl 

Clear screen and home cursor (P*) 

clreol, 

el 

ce 

Clear to end of line (P) 

clreos. 

ed 

cd 

Clear to end of display (P*) 

columnaddress, 

hpa 

ch 

Set cursor column (PG) 

commandcharacter. 

emdeh 

CC 

Term, settable cmd char in prototype 

cursoraddress, 

cup 

cm 

Screen rel. cursor motion row #1 col #2 (PG 

cursordown. 

cudl 

do 

Down one line 

cursorhome, 

home 

ho 

Home cursor (if no cup) 

cursorinvisible, 

civis 

vi 

Make cursor invisible 

cursorjeft, 

cubl 

le 

Move cursor left one space 

cursormemaddress, 

mrcup 

CM 

Memory relative cursor addressing 

cursor_normal, 

cnorm 

ve 

Make cursor appear normal (undo vs/vi) 

cursorright, 

cufl 

nd 

Non-destructive space (cursor right) 

cursortoll. 

11 

11 

Last line, first column (if no cup) 

cursor_up. 

cuul 

up 

Upline (cursor up) 

cursorvisible, 

cvvis 

vs 

Make cursor very visible 

deletecharacter, 

dehl 

dc 

Delete character (P*) 

10/84 


- 2 - 

10/84 



TERMINFO (4) 


TERMINFCK4) 


deleteline, 

dll 

dl 

disstatusline, 

dsl 

ds 

down_half_line. 

hd 

hd 

enteraltcharsetmode. 

smacs 

as 

enterblinkmode, 

blink 

mb 

enter_bold_mode. 

bold 

md 

entercamode, 

smcup 

ti 

enterdeletemode. 

smdc 

dm 

enterdimmode, 

dim 

mh 

enter_insert_mode, 

smir 

im 

enter jjrotectedmode, 

prot 

mp 

enter_reverse_mode, 

rev 

mr 

enter_secure_mode, 

invis 

mk 

enter_standout_mode. 

smso 

so 

enterjtnderline mode, 

smul 

us 

erase_chars 

ech 

ec 

exit_alt_charset_mode. 

rmacs 

ae 

exitattributemode, 

sgrO 

me 

exit_ca_mode, 

rmcup 

te 

exit_delete_mode, 

rmdc 

ed 

exit_insert_mode. 

rmir 

ei 

exit_standout_mode. 

rmso 

se 

exitunderlinemode, 

rmul 

ue 

flash_screen, 

flash 

vb 

form_feed. 

ff 

IT 

from_status_line, 

fsl 

fs 

init_l string. 

isl 

il 

init_2string, 

is2 

i2 

init_3string, 

is3 

i3 

init_file, 

if 

if 

insertcharacter, 

ichl 

ic 

insertjine, 

ill 

al 

insert_padding. 

ip 

'P 

key_backspace. 

kbs 

kb 

key_catab, 

ktbc 

ka 

key_clear, 

kclr 

kC 

key_ctab. 

kctab 

kt 

key_dc. 

kdchl 

kD 

keydl, 

kdll 

kL 

keydown, 

kcudl 

kd 

key_eic, 

krmir 

kM 

key_eol, 

kel 

kE 

key_eos, 

ked 

kS 

keyfO, 

kfO 

kO 

keyfl. 

kfl 

kl 

keyflO, 

kflO 

ka 

key_f2, 

kf2 

k2 

key f3. 

kf3 

k3 

key_f4, 

kf4 

k4 

key_f5. 

kf5 

k5 

key_f6, 

kf6 

k6 

key_f7, 

kf7 

k7 

key_f8, 

kf8 

k8 

key_f9. 

kf9 

k9 

key_home, 

khome 

kh 

keyic, 

kichl 

kl 

key_il. 

kill 

kA 
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Delete line (P*) 

Disable status line 

Half-line down (forward 1/2 linefeed) 
Start alternate character set (P) 

Turn on blinking 
Turn on bold (extra bright) mode 
String to begin programs that use cup 
Delete mode (enter) 

Turn on half-bright mode 
Insert mode (enter); 

Turn on protected mode 

Turn on reverse video mode 

Turn on blank mode (chars invisible) 

Begin stand out mode 

Start underscore mode 

Erase #1 characters (PG) 

End alternate character set (P) 

Turn off all attributes 

String to end programs that use cup 

End delete mode 

End insert mode 

End stand out mode 

End underscore mode 

Visible bell (may not move cursor) 

Hardcopy terminal page eject (P*) 

Return from status line 

Terminal initialization string 

Terminal initialization string 

Terminal initialization string 

Name of file containing is 

Insert character (P) 

Add new blank line (P*) 

Insert pad after character inserted (P*) 

Sent by backspace key 

Sent by clear-all-tabs key 

Sent by clear screen or erase key 

Sent by clear-tab key 

Sent by delete character key 

Sent by delete line key 

Sent by terminal down arrow key 

Sent by rmir or smir in insert mode 

Sent by clear-to-end-of-line key 

Sent by clear-to-end-of-screen key 

Sent by function key fO 

Sent by function key fl 

Sent by function key flO 

Sent by function key f2 

Sent by function key f3 

Sent by function key f4 

Sent by function key f5 

Sent by function key f6 

Sent by function key f7 

Sent by function key f8 

Sent by function key f9 

Sent by home key 

Sent by ins char/enter ins mode key 
Sent by insert line 
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keyjeft, 

kcubl 

kl 

Sent by terminal left arrow key 

key_ll, 

kll 

kH 

Sent by home-down key 

keynpage, 

knp 

kN 

Sent by next-page key 

key_ppag e . 

kpp 

kP 

Sent by previous-page key 

keyright. 

kcufl 

kr 

Sent by terminal right arrow key 

key_sf, 

kind 

kF 

Sent by scroll-forward/down key 

key_sr. 

kri 

kR 

Sent by scroll-backward/up key 

key_stab, 

khts 

kT 

Sent by set-tab key 

keyup, 

kcuul 

ku 

Sent by terminal up arrow key 

keypadjocal. 

rmkx 

ke 

Out of "keypad transmit" mode 

keypad_xmit, 

smkx 

ks 

Put terminal in "keypad transmit" mode 

lab_f0. 

lfO 

10 

Labels on function key fO if not fO 

labfl. 

Ifl 

11 

Labels on function key fl if not fl 

lab flO, 

lflO 

la 

Labels on function key flO if not flO 

lab_f2. 

lf2 

12 

Labels on function key f2 if not f2 

lab_f3, 

lf3 

13 

Labels on function key f3 if not f3 

lab_f4. 

lf4 

14 

Labels on function key f4 if not f4 

lab f5, 

lf5 

15 

Labels on function key f5 if not f5 

lab_f6, 

lf6 

16 

Labels on function key f6 if not f6 

lab f7. 

1(7 

17 

Labels on function key f7 if not f7 

lab_f8. 

lf8 

18 

Labels on function key f8 if not f8 

lab_f9, 

lf9 

19 

Labels on function key f9 if not f9 

metaon, 

smm 

mm 

Turn on "meta mode" (8th bit) 

meta_off, 

rmm 

mo 

Turn off "meta mode" 

newline, 

nel 

nw 

Newline (behaves like cr followed by If) 

padchar, 

pad 

pc 

Pad character (rather than null) 

parm_dch, 

dch 

DC 

Delete #1 chars (PG*) 

parm_delete_line, 

dl 

DL 

Delete #1 lines (PG*) 

parm_down_cursor, 

cud 

DO 

Move cursor down #1 lines (PG*) 

parmjch, 

ich 

IC 

Insert #1 blank chars (PG*) 

parmindex, 

indn 

SF 

Scroll forward #1 lines (PG) 

parminsertline, 

il 

AL 

Add #1 new blank lines (PG*) 

parm_left_cursor, 

cub 

LE 

Move cursor left #1 spaces (PG) 

parmrightcursor, 

cuf 

RI 

Move cursor right #1 spaces (PG*) 

parmrindex, 

rin 

SR 

Scroll backward #1 lines (PG) 

parmjtp cursor, 

cuu 

UP 

Move cursor up #1 lines (PG*) 

pkeykey, 

pfkey 

pk 

Prog funct key #1 to type string #2 

pkeyjocal. 

pfloc 

P> 

Prog funct key #1 to execute string #2 

pkeyxmit, 

pfx 

px 

Prog funct key #1 to xmit string #2 

printscreen. 

mcO 

ps 

Print contents of the screen 

prtr_off, 

mc4 

pf 

Turn off the printer 

prtr_on, 

mc5 

po 

Turn on the printer 

repeat_char, 

rep 

r P 

Repeat char #1 #2 times. (PG*) 

resetl string, 

rsl 

rl 

Reset terminal completely to sane modes. 

reset_2string, 

rs2 

r2 

Reset terminal completely to sane modes. 

reset_3string, 

rs3 

r3 

Reset terminal completely to sane modes. 

resetfile, 

rf 

rf 

Name of file containing reset string 

restorecursor. 

rc 

rc 

Restore cursor to position of last sc 

rowaddress, 

vpa 

cv 

Vertical position absolute (set row) (PG) 

save_cursor, 

sc 

sc 

Save cursor position (P) 

scrollforward. 

ind 

sf 

Scroll text up (P) 

scrollreverse, 

ri 

sr 

Scroll text down (P) 

setattributes, 

sgr 

sa 

Define the video attributes (PG9) 

settab, 

hts 

St 

Set a tab in all rows, current column 

setwindow, 

wind 

wi 

Current window is lines #l-#2 cols #3-#4 

tab. 

ht 

ta 

Tab to next 8 space hardware tab stop 

to status line, 

tsl 

ts 

Go to status line, column #1 
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underline_char, 

uc 

uc 

Underscore one char and move past it 

uphalfline, 

hu 

hu 

Half-line up (reverse 1/2 linefeed) 

init_prog, 

iprog 

iP 

Path name of program for init 

key_a 1 , 

kal 

K1 

Upper left of keypad 

key_a3, 

ka3 

K3 

Upper right of keypad 

key_b2, 

kb2 

K2 

Center of keypad 

keycl. 

kcl 

K4 

Lower left of keypad 

key_c3, 

kc3 

K5 

Lower right of keypad 

prtrnon, 

mc5p 

pO 

Turn on the printer for #1 bytes 


A Sample Entry 

The following entry, which describes the Concept— 100, is among the more 
complex entries in the terminfo file as of this writing. 

concept 100 IclOO! concept 1 c104 ! c100-4p I concept 100, 

am, be 1 = ~G , blank=\EH, blink = \EC, clear = A L$<2*> , cnorm = \Ew, 
cols#80, cr= A M$<9>, cub1 = A H, cud 1 = A J , cuf 1 =\E= , 
cup=\Ea%p1%' ' %+%c%p2%' ' %+%c , 

cuu1=\E; , cvvis = \EW, db , dch1=\E A A$< 16*> , dim=\EE, dl 1 =\E A B$ <3*> , 
ed=\E A C$<16*>, el = \E A U$ < 1 6> , eo, f lash = \Ek$<20>\EK , ht = \t$<8>, 
il 1=\E A R$<3*> , in, ind = A J, . ind= A J$<9> , ip = $<16*>, 
is2 = \EU\Ef \E7\E5\E8\El\ENH\EK\E\2 0 0\Eo&\2 0 0\Eo\47\E , 
kbs= A h, kcub1=\E>, kcud1=\E<, kcuf 1 =\E= , kcuu1=\E; , 
kf 1 =\E5 , kf 2 =\E6 , kf3=\E7, khome = \E? , 

lines#24, mir, pb#9600, prot=\EI, rep=\Er%p 1 %c%p2 % ' '%+%c$<.2*>, 

rev=\ED, rmcup=\Ev $<6>\Ep\r\n, rmir=\E\200, rmkx=\Ex, 
rmso=\Ed\Ee, rmul=\Eg, rmul=\Eg, sgr0=\EN\200 , 
smcup=\EU\Ev 8p\Ep\r, smir=\E A P, smkx=\EX, smso=\EE\ED, 
smul=\EG, tabs, ul , vt#8 , xenl , 

Entries may continue onto multiple lines by placing white space at the begin- 
ning of each line except the first. Comments may be included on lines begin- 
ning with “#”. Capabilities in terminfo are of three types: Boolean capabili- 
ties which indicate that the terminal has some particular feature, numeric 
capabilities giving the size of the terminal or the size of particular delays, and 
string capabilities, which give a sequence which can be used to perform particu- 
lar terminal operations. 

Types of Capabilities 

All capabilities have names. For instance, the fact that the Concept has 
automatic margins (i.e., an automatic return and linefeed when the end of a 
line is reached) is indicated by the capability am. Hence the description of the 
Concept includes am. Numeric capabilities are followed by the character ‘#’ 
and then the value. Thus cols, which indicates the number of columns the ter- 
minal has, gives the value ‘80’ for the Concept. 

Finally, string valued capabilities, such as el (clear to end of line sequence) are 
given by the two-character code, an “=’, and then a string ending at the next 
following A delay in milliseconds may appear anywhere in such a capabil- 
ity, enclosed in $<..> brackets, as in el=\EK$<3>, and padding characters 
are supplied by tputs to provide this delay. The delay can be either a number, 
e.g., ‘20’, or a number followed by an **’, i.e., ‘3*’. A **’ indicates that the 
padding required is proportional to the number of lines affected by the opera- 
tion, and the amount given is the per-afifected-unit padding required. (In the 
case of insert character, the factor is still the number of lines affected. This is 
always one unless the terminal has xenl and the software uses it.) When a **’ 
is specified, it is sometimes useful to give a delay of the form ‘3.5’ to specify a 
delay per unit to tenths of milliseconds. (Only one decimal place is allowed.) 
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A number of escape sequences are provided in the string valued capabilities for 
easy encoding of characters there. Both \E and \e map to an ESCAPE charac- 
ter, "x maps to a control-x for any appropriate x, and the sequences \n \1 \r \t 
\b \f \s give a newline, linefeed, return, tab, backspace, formfeed, and space. 
Other escapes include V for ", \\ for \, \, for comma, \: for :, and \0 for null. 
(\0 will produce \200, which does not terminate a string but behaves as a null 
character on most terminals.) Finally, characters may be given as three octal 
digits after a \. 

Sometimes individual capabilities must be commented out. To do this, put a 
period before the capability name. For example, see the second ind in the 
example above. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The most effective 
way to prepare a terminal description is by imitating the description of a simi- 
lar terminal in terminfo and to build up a description gradually, using partial 
descriptions with vi to check that they are correct. Be aware that a very 
unusual terminal may expose deficiencies in the ability of the terminfo file to 
describe it or bugs in vi. To easily test a new terminal description you can set 
the environment variable TERMINFO to a pathname of a directory containing 
the compiled description you are working on and programs will look there 
rather than in lusrlliblterminfo. To get the padding for insert line right (if the 
terminal manufacturer did not document it) a severe test is to edit /etc/passwd 
at 9600 baud, delete 16 or so lines from the middle of the screen, then hit the 
V key several times quickly. If the terminal messes up, more padding is usu- 
ally needed. A similar test can be used for insert character. 

Basic Capabilities 

The number of columns on each line for the terminal is given by the cols 
numeric capability. If the terminal is a CRT, then the number of lines on the 
screen is given by the lines capability. If the terminal wraps around to the 
beginning of the next line when it reaches the right margin, then it should have 
the am capability. If the terminal can clear its screen, leaving the cursor in the 
home position, then this is given by the clear string capability. If the terminal 
overstrikes (rather than clearing a position when a character is struck over) 
then it should have the os capability. If the terminal is a printing terminal, 
with no soft copy unit, give it both he and os. (os applies to storage scope ter- 
minals, such as TEKTRONIX 4010 series, as well as hard copy and APL termi- 
nals.) If there is a code to move the cursor to the left edge of the current row, 
give this as cr. (Normally this will be carriage return, control M.) If there is 
a code to produce an audible signal (bell, beep, etc) give this as bel. 

If there is a code to move the cursor one position to the left (such as back- 
space) that capability should be given as cubl. Similarly, codes to move to the 
right, up, and down should be given as cufl, cuul, and cudl. These local cursor 
motions should not alter the text they pass over, for example, you would not 
normally use ‘cufl= ’ because the space would erase the character moved over. 

A very important point here is that the local cursor motions encoded in ter- 
minfo are undefined at the left and top edges of a CRT terminal. Programs 
should never attempt to backspace around the left edge, unless bw is given, and 
never attempt to go up locally off the top. In order to scroll text up, a program 
will go to the bottom left corner of the screen and send the ind (index) string. 

To scroll text down, a program goes to the top left corner of the screen and 
sends the ri (reverse index) string. The strings ind and ri are undefined when 
not on their respective corners of the screen. 
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Parameterized versions of the scrolling sequences are indn and rin which have 
the same semantics as ind and ri except that they take one parameter, and 
scroll that many lines. They are also undefined except at the appropriate edge 
of the screen. 

The am capability tells whether the cursor sticks at the right edge of the screen 
when text is output, but this does not necessarily apply to a cufl from the last 
column. The only local motion which is defined from the left edge is if bw is 
given, then a cubl from the left edge will move to the right edge of the previ- 
ous row. If bw is not given, the effect is undefined. This is useful for drawing 
a box around the edge of the screen, for example. If the terminal has switch 
selectable automatic margins, the terminfo file usually assumes that this is on; 
i.e., am. If the terminal has a command which moves to the first column of the 
next line, that command can be given as nel (newline). It does not matter if 
the command clears the remainder of the current line, so if the terminal has no 
cr and If it may still be possible to craft a working nel out of one or both of 
them. 

These capabilities suffice to describe hardcopy and glass-tty terminals. Thus 
the model 33 teletype is described as 

33 1 tty33 ! tty 1 model 33 teletype, 

bel= A G, cols#72, cr = “M, cud1 = "J, he, ind= / 'J, os, 
while the Lear Siegler ADM— 3 is described as 
adm3 1 3 1 lsi adm3 , 

am, bel=~G, clear='Z, cols#80, cr="M, cub1= A H, cud1= A J, 
ind = "'J, lines#24, 

Parameterized Strings 

Cursor addressing and other strings requiring parameters in the terminal are 
described by a parameterized string capability, with printf OS ) like escapes % x 
in it. For example, to address the cursor, the cup capability is given, using two 
parameters: the row and column to address to. (Rows and columns are num- 
bered from zero and refer to the physical screen visible to the user, not to any 
unseen memory.) If the terminal has memory relative cursor addressing, that 
can be indicated by mrcup. 

The parameter mechanism uses a stack and special % codes to manipulate it. 
Typically a sequence will push one of the parameters onto the stack and then 
print it in some format. Often more complex operations are necessary. 

The % encodings have the following meanings: 


%% 

outputs '%’ 

%d 

print pop() as in printf 

%2d 

print pop() like %2d 

%3d 

print popO like %3d 

%02d 


%03d 

as in printf 

%c 

print popO gives %c 

%s 

print popO gives %s 

%p[ 1 -9] 

push ith parm 

%P[a-z] 

set variable [a-z] to popO 

%g[a-z] 

get variable [a-z] and push it 

%’c’ 

char constant c 

%(nn} 

integer constant nn 

%+ %- %* %/ %m 

arithmetic (%m is mod): push(pop() op popO) 


10/84 


- 7 - 


10/84 



TERMINFO (4) 


TERMINFO (4) 


%& %\ %' 
%= %>%< 
%\ %' 

%i 


bit operations: push (pop 0 op popO) 
logical operations: push (pop 0 op popO) 
unary operations push(op popO) 
add 1 to first two parms (for ANSI terminals) 


%? expr %t thenpart %e elsepart %; 

if-then-else, %e elsepart is optional. 
else-iFs are possible ala Algol 68: 

%? Cj %t b, %e C 2 %t bj %e %t b^ %e %t b^ %e %; 

c- are conditions, b- are bodies. 

1 1 

Binary operations are in postfix form with the operands in the usual order. 
That is, to get x-5 one would use ''%gx%{5)%-''. 

Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, 
needs to be sent \E&al2c03Y padded for 6 milliseconds. Note that the order 
of the rows and columns is inverted here, and that the row and column are 
printed as two digits. Thus its cup capability is cup=6\E&%p2%2dc%pl%2dY. 

The Microterm ACT-IV needs the current row and column sent preceded by a 
*T, with the row and column simply encoded in binary, cup=’'T%pl%c%p2%c. 
Terminals which use %c need to be able to backspace the cursor (cubl), and to 
move the cursor up one line on the screen (cuul). This is necessary because it 
is not always safe to transmit \n ~D and \r, as the system may change or dis- 
card them. (The library routines dealing with terminfo set tty modes so that 
tabs are never expanded, so \t is safe to send. This turns out to be essential for 
the Ann Arbor 4080.) 

A final example is the LSI ADM-3a, which uses row and column offset by a 
blank character, thus cup=\E=%pl%’ ’%+%c%p2%’ '%+%c. After sending 
‘\E=\ this pushes the first parameter, pushes the ASCII value for a space (32), 
adds them (pushing the sum on the stack in place of the two previous values) 
and outputs that value as a character. Then the same is done for the second 
parameter. More complex arithmetic is possible using the stack. 

If the terminal has row or column absolute cursor addressing, these can be 
given as single parameter capabilities hpa (horizontal position absolute) and vpa 
(vertical position absolute). Sometimes these are shorter than the more general 
two parameter sequence (as with the hp2645) and can be used in preference to 
cup . If there are parameterized local motions (e.g., move n spaces to the right) 
these can be given as cud, cub, cuf, and cuu with a single parameter indicating 
how many spaces to move. These are primarily useful if the terminal does not 
have cup, such as the TEKTRONIX 4025. 

Cursor Motions 

If the terminal has a fast way to home the cursor (to very upper left corner of 
screen) then this can be given as home; similarly a fast way of getting to the 
lower left-hand corner can be given as II; this may involve going up with cuul 
from the home position, but a program should never do this itself (unless II 
does) because it can make no assumption about the effect of moving up from 
the home position. Note that the home position is the same as addressing to 
(0,0): to the top left corner of the screen, not of memory. (Thus, the \EH 
sequence on Hewlett-Packard terminals cannot be used for home.) 

Area Clears 

If the terminal can clear from the current position to the end of the line, leav- 
ing the cursor where it is, this should be given as el. If the terminal can clear 
from the current position to the end of the display, then this should be given as 
ed Ed is only defined from the first column of a line. (Thus, it can be simu- 
lated by a request to delete a large number of lines, if a true ed is not 
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available.) 

Insert/delete line 

If the terminal can open a new blank line before the line where the cursor is, 
this should be given as ill; this is done only from the first position of a line. 
The cursor must then appear on the newly blank line. If the terminal can 
delete the line which the cursor is on, then this should be given as dll; this is 
done only from the first position on the line to be deleted. Versions of ill and 
dll which take a single parameter and insert or delete that many lines can be 
given as il and dl. If the terminal has a settable scrolling region (like the 
vtlOO) the command to set this can be described with the csr capability, which 
takes two parameters: the top and bottom lines of the scrolling region. The 
cursor position is, alas, undefined after using this command. It is possible to 
get the effect of insert or delete line using this command — the sc and re (save 
and restore cursor) commands are also useful. Inserting lines at the top or bot- 
tom of the screen can also be done using ri or ind on many terminals without a 
true insert/delete line, and is often faster even on terminals with those features. 

If the terminal has the ability to define a window as part of memory, which all 
commands affect, it should be given as the parameterized string wind. The four 
parameters are the starting and ending lines in memory and the starting and 
ending columns in memory, in that order. 

If the terminal can retain display memory above, then the da capability should 
be given; if display memory can be retained below, then db should be given. 
These indicate that deleting a line or scrolling may bring non-blank lines up 
from below or that scrolling back with ri may bring down non-blank lines. 

Insert/Delete Character 

There are two basic kinds of intelligent terminals with respect to insert/delete 
character which can be described using terminfo. The most common 
insert/delete character operations affect only the characters on the current line 
and shift characters off the end of the line rigidly. Other terminals, such as the 
Concept 100 and the Perkin Elmer Owl, make a distinction between typed and 
untyped blanks on the screen, shifting upon an insert or delete only to an 
untyped blank on the screen which is either eliminated, or expanded to two 
untyped blanks. You can determine the kind of terminal you have by clearing 
the screen and then typing text separated by cursor motions. Type abc def 
using local cursor motions (not spaces) between the abc and the def. Then 
position the cursor before the abc and put the terminal in insert mode. If typ- 
ing characters causes the rest of the line to shift rigidly and characters to fall 
off the end, then your terminal does not distinguish between blanks and 
untyped positions. If the abc shifts over to the def which then move together 
around the end of the current line and onto the next as you insert, you have the 
second type of terminal, and should give the capability in, which stands for 
insert null. While these are two logically separate attributes (one line vs. mul- 
tiline insert mode, and special treatment of untyped spaces) we have seen no 
terminals whose insert mode cannot be described with the single attribute. 

Terminfo can describe both terminals which have an insert mode, and terminals 
which send a simple sequence to open a blank position on the current line. 
Give as smir the sequence to get into insert mode. Give as rmir the sequence to 
leave insert mode. Now give as ichl any sequence needed to be sent just before 
sending the character to be inserted. Most terminals with a true insert mode 
will not give ichl; terminals which send a sequence to open a screen position 
should give it here. (If your terminal has both, insert mode is usually prefer- 
able to ichl. Do not give both unless the terminal actually requires both to be 
used in combination.) If post insert padding is needed, give this as a number of 
milliseconds in ip (a string option). Any other sequence which may need to be 
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sent after an insert of a single character may also be given in ip. If your termi- 
nal needs both to be placed into an ‘insert mode’ and a special code to precede 
each inserted character, then both smir/rmir and ichl can be given, and both 
will be used. The ich capability, with one parameter, n, will repeat the effects 
of ichl n times. 

It is occasionally necessary to move around while in insert mode to delete char- 
acters on the same line (e.g., if there is a tab after the insertion position). If 
your terminal allows motion while in insert mode you can give the capability 
mir to speed up inserting in this case. Omitting mir will affect only speed. 
Some terminals (notably Datamedia’s) must not have mir because of the way 
their insert mode works. 

Finally, you can specify dchl to delete a single character, dch with one parame- 
ter, n, to delete n characters, and delete mode by giving smdc and rmdc to 
enter and exit delete mode (any mode the terminal needs to be placed in for 
dchl to work). 

A command to erase n characters (equivalent to outputting n blanks without 
moving the cursor) can be given as ech with one parameter. 

Highlighting, Underlining, and Visible Bells 

If your terminal has one or more kinds of display attributes, these can be 
represented in a number of different ways. You should choose one display form 
as standout mode , representing a good, high contrast, easy-on-the-eyes, format 
for highlighting error messages and other attention getters. (If you have a 
choice, reverse video plus half-bright is good, or reverse video alone.) The 
sequences to enter and exit standout mode are given as smso and rmso, respec- 
tively. If the code to change into or out of standout mode leaves one or even 
two blank spaces on the screen, as the TVI 912 and Teleray 1061 do, then xmc 
should be given to tell how many spaces are left. 

Codes to begin underlining and end underlining can be given as smul and rmul 
respectively. If the terminal has a code to underline the current character and 
move the cursor one space to the right, such as the Microterm Mime, this can 
be given as uc. 

Other capabilities to enter various highlighting modes include blink (blinking) 
bold (bold or extra bright) dim (dim or half-bright) invis (blanking or invisible 
text) prot (protected) rev (reverse video) sgrO (turn off all attribute modes) 
smacs (enter alternate character set mode) and rmacs (exit alternate character 
set mode). Turning on any of these modes singly may or may not turn off 
other modes. 

If there is a sequence to set arbitrary combinations of modes, this should be 
given as sgr (set attributes), taking 9 parameters. Each parameter is either 0 
or 1, as the corresponding attribute is on or off. The 9 parameters are, in 
order: standout, underline, reverse, blink, dim, bold, blank, protect, alternate 
character set. Not all modes need be supported by sgr, only those for which 
corresponding separate attribute commands exist. 

Terminals with the “magic cookie” glitch (xmc) deposit special “cookies” when 
they receive mode-setting sequences, which affect the display algorithm rather 
than having extra bits for each character. Some terminals, such as the 
Hewlett-Packard 2621, automatically leave standout mode when they move to a 
new line or the cursor is addressed. Programs using standout mode should exit 
standout mode before moving the cursor or sending a newline, unless the msgr 
capability, asserting that it is safe to move in standout mode, is present. 

If the terminal has a way of flashing the screen to indicate an error quietly (a 
bell replacement) then this can be given as flash; it must not move the cursor. 
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If the cursor needs to be made more visible than normal when it is not on the 
bottom line (to make, for example, a non-blinking underline into an easier to 
find block or blinking underline) give this sequence as cvvis. If there is a way 
to make the cursor completely invisible, give that as civis. The capability 
cnorm should be given which undoes the effects of both of these modes. 

If the terminal needs to be in a special mode when running a program that uses 
these capabilities, the codes to enter and exit this mode can be given as smcup 
and rmcup. This arises, for example, from terminals like the Concept with 
more than one page of memory. If the terminal has only memory relative cur- 
sor addressing and not screen relative cursor addressing, a one screen-sized win- 
dow must be fixed into the terminal for cursor addressing to work properly. 
This is also used for the TEKTRONIX 4025, where smcup sets the command 
character to be the one used by terminfo. 

If your terminal correctly generates underlined characters (with no special 
codes needed) even though it does not overstrike, then you should give the 
capability ul. If overstrikes are erasable with a blank, then this should be indi- 
cated by giving eo. 

Keypad 

If the terminal has a keypad that transmits codes when the keys are pressed, 
this information can be given. Note that it is not possible to handle terminals 
where the keypad only works in local (this applies, for example, to the 
unshifted Hewlett-Packard 2621 keys). If the keypad can be set to transmit or 
not transmit, give these codes as smkx and rmkx. Otherwise the keypad is 
assumed to always transmit. The codes sent by the left arrow, right arrow, up 
arrow, down arrow, and home keys can be given as kcubl, kcufl, kcuul, kcudl, 

and khome respectively. If there are function keys such as fO, fl flO, the 

codes they send can be given as kfO, kfl, kflO. If these keys have labels 
other than the default fO through flO, the labels can be given as IfO, If 1, 

If 1 0. The codes transmitted by certain other special keys can be given: kll 
(home down), kbs (backspace), ktbc (clear all tabs), kctab (clear the tab stop 
in this column), kclr (clear screen or erase key), kdchl (delete character), kdll 
(delete line), krmir (exit insert mode), kel (clear to end of line), ked (clear to 
end of screen), kichl (insert character or enter insert mode), kill (insert line), 
knp (next page), kpp (previous page), kind (scroll forward/down), kri (scroll 
backward/up), khts (set a tab stop in this column). In addition, if the keypad 
has a 3 by 3 array of keys including the four arrow keys, the other five keys 
can be given as kal, ka3, kb2, kcl, and kc3. These keys are useful when the 
effects of a 3 by 3 directional pad are needed. 

Tabs and Initialization 

If the terminal has hardware tabs, the command to advance to the next tab 
stop can be given as ht (usually control I). A “backtab” command which 
moves leftward to the next tab stop can be given as cbt. By convention, if the 
teletype modes indicate that tabs are being expanded by the computer rather 
than being sent to the terminal, programs should not use ht or cbt even if they 
are present, since the user may not have the tab stops properly set. If the ter- 
minal has hardware tabs which are initially set every n spaces when the termi- 
nal is powered up, the numeric parameter it is given, showing the number of 
spaces the tabs are set to. This is normally used by the tsei command to deter- 
mine whether to set the mode for hardware tab expansion, and whether to set 
the tab stops. If the terminal has tab stops that can be saved in nonvolatile 
memory, the terminfo description can assume that they are properly set. 

Other capabilities include isl, is2, and is3, initialization strings for the termi- 
nal, iprog, the path name of a program to be run to initialize the terminal, and 
if, the name of a file containing long initialization strings. These strings are 
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expected to set the terminal into modes consistent with the rest of the terminfo 
description. They are normally sent to the terminal, by the tset program, each 
time the user logs in. They will be printed in the following order: isl; is2; set- 
ting tabs using tbc and hts; if; running the program iprog; and finally is3. Most 
initialization is done with is2. Special terminal modes can be set up without 
duplicating strings by putting the common sequences in is2 and special cases in 
isl and is3. A pair of sequences that does a harder reset from a totally unk- 
nown state can be analogously given as rsl, rs2, rf, and rs3. analogous to is2 
and if. These strings are output by the reset program, which is used when the 
terminal gets into a wedged state. Commands are normally placed in rs2 and 
rf only if they produce annoying effects on the screen and are not necessary 
when logging in. For example, the command to set the vtlOO into 80-column 
mode would normally be part of is2, but it causes an annoying glitch of the 
screen and is not normally needed since the terminal is usually already in 80 
column mode. 

If there are commands to set and clear tab stops, they can be given as tbc 
(clear all tab stops) and hts (set a tab stop in the current column of every 
row). If a more complex sequence is needed to set the tabs than can be 
described by this, the sequence can be placed in is2 or if. 

Delays 

Certain capabilities control padding in the teletype driver. These are primarily 
needed by hard copy terminals, and are used by the tset program to set teletype 
modes appropriately. Delays embedded in the capabilities cr, ind, cubl, ff, and 
tab will cause the appropriate delay bits to be set in the teletype driver. If pb 
(padding baud rate) is given, these values can be ignored at baud rates below 
the value of pb. 

Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, then this 
can be given as pad. Only the first character of the pad string is used. 

If the terminal has an extra “status line” that is not normally used by software, 
this fact can be indicated. If the status line is viewed as an extra line below 
the bottom line, into which one can cursor address normally (such as the 
Heathkit hl9's 25th line, or the 24th line of a vtlOO which is set to a 23-line 
scrolling region), the capability hs should be given. Special strings to go to the 
beginning of the status line and to return from the status line can be given as 
tsl and fsl. (fsl must leave the cursor position in the same place it was before 
tsl. If necessary, the sc and rc strings can be included in tsl and fsl to get this 
effect.) The parameter tsl takes one parameter, which is the column number of 
the status line the cursor is to be moved to. If escape sequences and other spe- 
cial commands, such as tab, work while in the status line, the flag eslok can be 
given. A string which turns off the status line (or otherwise erases its contents) 
should be given as dsl. If the terminal has commands to save and restore the 
position of the cursor, give them as sc and rc. The status line is normally 
assumed to be the same width as the rest of the screen, e.g., cols. If the status 
line is a different width (possibly because the terminal does not allow an entire 
line to be loaded) the width, in columns, can be indicated with the numeric 
parameter wsl. 

If the terminal can move up or down half a line, this can be indicated with hu 
(half-line up) and hd (half-line down). This is primarily useful for superscripts 
and subscripts on hardcopy terminals. If a hardcopy terminal can eject to the 
next page (form feed), give this as IT (usually control L). 

If there is a command to repeat a given character a given number of times (to 
save time transmitting a large number of identical characters) this can be 
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indicated with the parameterized string rep. The first parameter is the charac- 
ter to be repeated and the second is the number of times to repeat it. Thus, 
tparm (repea t_char, Y, 10) is the same as ‘xxxxxxxxxx’. 

If the terminal has a settable command character, such as the TEKTRONIX 
4025, this can be indicated with cmdch. A prototype command character is 
chosen which is used in all capabilities. This character is given in the cmdch 
capability to identify it. The following convention is supported on some UNIX 
systems: The environment is to be searched for a CC variable, and if found, all 
occurrences of the prototype character are replaced with the character in the 
environment variable. 

Terminal descriptions that do not represent a specific kind of known terminal, 
such as switch, dialup, patch, and network, should include the gn (generic) 
capability so that programs can complain that they do not know how to talk to 
the terminal. (This capability does not apply to virtual terminal descriptions 
for which the escape sequences are known.) 

If the terminal uses xon/xoff handshaking for flow control, give xon. Padding 
information should still be included so that routines can make better decisions 
about costs, but actual pad characters will not be transmitted. 

If the terminal has a “meta key” which acts as a shift key, setting the 8th bit 
of any character transmitted, this fact can be indicated with km. Otherwise, 
software will assume that the 8th bit is parity and it will usually be cleared. If 
strings exist to turn this “meta mode” on and off, they can be given as smm 
and rmm. 

If the terminal has more lines of memory than will fit on the screen at once, 
the number of lines of memory can be indicated with lm. A value of lm#0 
indicates that the number of lines is not fixed, but that there is still more 
memory than fits on the screen. 

If the terminal is one of those supported by the UNIX system virtual terminal 
protocol, the terminal number can be given as vt. 

Media copy strings which control an auxiliary printer connected to the terminal 
can be given as mcO: print the contents of the screen, mc4: turn off the 
printer, and mc5: turn on the printer. When the printer is on, all text sent to 
the terminal will be sent to the printer. It is undefined whether the text is also 
displayed on the terminal screen when the printer is on. A variation mc5p 
takes one parameter, and leaves the printer on for as many characters as the 
value of the parameter, then turns the printer off. The parameter should not 
exceed 255. All text, including mc4, is transparently passed to the printer 
while an mc5p is in effect. 

Strings to program function keys can be given as pfkey, pfloc, and pfx. Each of 
these strings takes two parameters: the function key number to program (from 
0 to 10) and the string to program it with. Function key numbers out of this 
range may program undefined keys in a terminal dependent manner. The 
difference between the capabilities is that pfkey causes pressing the given key 
to be the same as the user typing the given string; pfloc causes the string to be 
executed by the terminal in local; and pfx causes the string to be transmitted to 
the computer. 
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Glitches and Braindamage 

Hazeltine terminals, which do not allow characters to be displayed should 
indicate hz. 

Terminals which ignore a linefeed immediately after an am wrap, such as the 
Concept and vtlOO, should indicate xenl. 

If el is required to get rid of standout (instead of merely writing normal text on 
top of it), xhp should be given. 

Teleray terminals, where tabs turn all characters moved over to blanks, should 
indicate xt (destructive tabs). This glitch is also taken to mean that it is not 
possible to position the cursor on top of a “magic cookie”, that to erase stan- 
dout mode it is instead necessary to use delete and insert line. 

The Beehive Superbee, which is unable to correctly transmit the escape or con- 
trol C characters, has xsb, indicating that the fl key is used for escape and f2 
for control C. (Only certain Superbees have this problem, depending on the 
ROM.) 

Other specific terminal problems may be corrected by adding more capabilities 
of the form xx. 

Similar Terminals 

If there are two very similar terminals, one can be defined as being just like the 
other with certain exceptions. The string capability use can be given with the 
name of the similar terminal. The capabilities given before use override those 
in the terminal type invoked by use. A capability can be cancelled by placing 
xx@ to the left of the capability definition, where xx is the capability. For 
example, the entry 

2621-nl, smkx@, rmkx@, use=2621, 

defines a 2621-nl that does not have the smkx or rmkx capabilities, and hence 
does not turn on the function key labels when in visual mode. This is useful for 
different modes for a terminal, or for different user preferences. 

FILES 

/usr/lib/terminfo/?/* files containing terminal descriptions 
SEE ALSO 

curses(3X), printf(3S), term(5). 

3B2 Computer System Terminal Information Utilities Guide. 
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NAME 

timezone — set default system time zone 

SYNOPSIS 

/etc/TIMEZONE 

DESCRIPTION 

This file sets and exports the time zone environmental variable TZ. 
This file is "dotted" into other files that must know the time zone. 
EXAMPLES 

/etc/TIMEZONE for the east coast: 

# Time Zone 
TZ=EST5EDT 
export TZ 


SEE ALSO 

ctime(3C), profile(4). 

rc2(lM) in the 3B2 Computer System Administration Utilities Guide. 
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NAME 

utmp, wtmp — utmp and wtmp entry formats 
SYNOPSIS 

#include <sys/types.h> 

#include <utmp.h> 

DESCRIPTION 

These files, which hold user and accounting information for such commands as 
who ( 1 ) , write {\ ), and login(\), have the following structure as defined by 

<utmp.h>: 

"/etc/utmp" 

"/etc/wtmp" 

utuser 

11 11 11 1 . 
struct utmp { 


char 

ut_user[8]; 

/* User login name */ 

char 

ut_id[4]; 

/* /etc/inittab id (usually line #) */ 

char 

ut_line[12] 

; /* device name (console, Inxx) */ 

short 

ut_pid; /» 

process id */ 

short 

uttype; /* 

type of entry */ 

struct 

exitstatus 

{ 

short 

e termination; /« Process termination status 

short 

eexit; 

/* Process exit status */ 

j ut exit; 

/* The exit status of a process 


» marked as DEADPROCESS. »/ 


time t ut time;/* time entry was made »/ 


/* Definitions for uttype */ 

11 llp-1 11 1. 

#define EMPTY 0 
#define RUNLVL 1 

#define BOOT TIME 2 
#define OLD TIME 3 
#define NEW TIME 4 

#define INIT PROCESS 5 /* Process spawned by "init" */ 

#define LOGINPROCESS 6 /* A "getty" process waiting for login */ 

#define USERPROCESS7 /» A user process */ 

#define DEAD PROCESS 8 

#define ACCOUNTING 9 

#define UTMAXTYPE ACCOUNTING /* Largest legal value of ut_type */ 

/* Special strings or formats used in the "utline" field when */ 

/* accounting for something other than a process »/ 

/» No string for the utjine field can be more than 1 1 chars + */ 

/* a NULL in length */ 

11 llp-1 1. 

#define RUNLVL_MSG "run-level %c" 

#define BOOT MSG "system boot" 

#define OTIME MSG "old time" 

#define NTIME MSG "new time" 


1 lp-1 1. 

#define UTMP FILE 
#define WTMP FILE 
1 1 1 . 

#define ut name 
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FILES 

/ usr/include/utmp.h 

/etc/utmp 

/etc/wtmp 

SEE ALSO 

getut(3C). 

login (1), who(l), write(l) in the 3B2 Computer System User Reference 
Manual. 
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NAME 

intro — introduction to miscellany 
DESCRIPTION 

This section describes miscellaneous facilities such as macro packages, charac- 
ter set tables, etc. 
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NAME 

ascii — map of ASCII character set 

SYNOPSIS 

cat /usr/pub/ascii 

DESCRIPTION 

Ascii is a map of the ASCII character set, giving both octal and hexadecimal 
equivalents of each character, to be printed as needed. It contains: 


| 000 

nu 1 

| 00 1 

soh 

| 002 

stx 

| 003 

c t X 

| 004 

cot 

| 005 

cnq 

| 006 

ack 

| 007 

be 1 

| 0 1 0 

bs 

j 0 1 1 

hi 

j 0 1 2 

n 1 

1 0 1 3 

vt 

j 0 1 4 

np 

j 01 5 

c r 

j 0 1 6 

so 

j 0 1 7 

s i 

j 020 

d 1 e 

j 02 1 

dc 1 

| 022 

dc2 

j 023 

dc3 

[024 

dc4 

| 025 

nak 

j 026 

syn 

| 027 

e t b 

| 030 

can 

[031 

em 

| 032 

sub 

1 033 

esc 

| 034 

fs 

| 035 

gs 

| 036 

r s 

| 037 

us 

j 040 

sp 

j 04 1 

! 

| 042 

" 

1 043 

# 

| 044 

$ 

| 045 

< 7 , 

j 046 

& 

| 047 

' 

| 050 

( 

| 05 1 

) 

j 052 

* 

1 053 

+ 

| 054 


| 055 

- 

| 056 


057 

/ 

| 060 

0 

j 06 1 

1 

j 062 

2 

1 063 

3 

1 064 

4 

j 065 

5 

066 

6 

1 067 

7 

| 070 

8 

j 07 1 

9 

j 072 


| 073 

; 

1 074 

< 

j 075 

= 

j 076 

> 

j 077 

•> 

| 100 

@ 

| 101 

A 

j 102 

B 

| 103 

c 

| 104 

D 

105 

E 

| 106 

F 

| 107 

G 

| 1 10 

H 

| 1 1 1 

I 

j 1 12 

J 

| 1 13 

K 

| 1 14 

L 

1 1 15 

M 

| 1 16 

N 

| 1 17 

O 

| 120 

P 

| 121 

Q 

122 

R 

| 123 

S 

| 124 

T 

1 125 

U 

| 126 

V 

| 127 

W 

| 130 

X 

j 131 

Y 

[ 132 

Z 

1 133 

[ 

| 134 

\ 

1 135 

1 

| 136 

* 

j 137 


| 140 

' 

| 141 

a 

| 142 

b 

143 

c 

| 144 

d 

j 145 

e 

j 146 

f 

| 147 

g 

| 150 

h 

| 151 

i 

| 152 

j 

153 

k 

| 154 

1 

1 155 

m 

| 156 

n 

| 157 

0 

| 160 

P 

| 161 

q 

| 162 

r 

| 163 

s 

| 164 

t 

j 165 

u 

166 

V 

| 167 

w 

| 170 

X 

| 171 

y 

1 172 

z 

| 173 

1 

| 174 

1 

1 175 

1 

| 176 


1 177 

del 

| 00 

nu 1 

I 01 

soh 

1 02 

s t x 

1 03 

etx 

| 04 

eot 

1 05 

enq 

| 06 

ack 

| 07 

be 1 

| 08 

bs 

j 09 

ht 

j 0a 

n 1 

| 0b 

vt 

| 0c 

np 

Od 

cr 

| Oe 

so 

| Of 

s i 

1 10 

d 1 e 

1 1 1 

dc 1 

| 12 

dc2 

1 13 

dc3 

1 14 

dc4 

1 15 

nak 

1 1 6 

syn 

1 17 

et b 

1 18 

can 

19 

em 

I >a 

sub 

1 lb 

esc 

1 lc 

f s 

j Id 

gs 

1 le 

rs 

1 1 f 

us 

| 20 

sp 

I 21 

1 

22 

" 

| 23 

# 

1 24 

$ 

| 25 

% 

| 26 

& 

1 27 

r 

| 28 

( 

1 29 

) 

i 2a 

* 

1 2b 

+ 

1 2c 


I 2d 

- 

| 2e 


| 2 f 

/ 

1 30 

0 

1 31 

1 

1 32 

2 

j 33 

3 

1 34 

4 

1 35 

5 

1 36 

6 

| 37 

7 

| 38 

8 

! 39 

9 

1 3a 


| 3b 

\ 

1 3c 

< 

1 3d 

= 

3e 

> 

1 3 f 

■> 

| 40 

@ 

i 41 

A 

1 42 

B 

| 43 

C 

| 44 

D 

1 45 

E 

| 46 

F 

1 47 

G 

oo 

H 

| 49 

1 

j 4a 

J 

| 4b 

K 

| 4c 

L 

4d 

M 

j 4e 

N 

1 4f 

O 

1 50 

P 

| 51 

Q 

1 52 

R 

1 53 

S 

| 54 

T 

I 55 

U 

| 56 

V 

| 57 

W 

I 58 

X 

1 59 

Y 

1 5a 

Z 

1 5b 

[ 

1 5c 

\ 

1 5d 

] 

| 5e 

A 

1 5 f 


| 60 

- 

j 61 

a 

i 62 

b 

1 63 

c 

| 64 

d 

j 65 

e 

| 66 

f 

| 67 

g 

| 68 

h 

| 69 

i 

| 6a 

j 

| 6b 

k 

| 6c 

1 

| 6d 

m 

j 6e 

n 

1 6 f 

0 

| 70 

P 

I 71 

q 

72 

r 

| 73 

s 

1 74 

t 

1 75 

u 

1 76 

V 

| 77 

w 

1 78 

X 

i 79 

y 

i 7a 

z 

1 7b 

( 

1 7c 

1 

1 7d 

) 

1 7e 

~ 

1 7 f 

de 1 


FILES 

/usr/pub/ascii 
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NAME 

environ — user environment 
DESCRIPTION 

An array of strings called the “environment” is made available by execi 2) 
when a process begins. By convention, these strings have the form 
“name=value”. The following names are used by various commands: 

PATH The sequence of directory prefixes that sh( 1), time( 1), nice (1), 
nohup (1), etc., apply in searching for a file known by an incomplete 
path name. The prefixes are separated by colons (:). Login! 1) sets 

PATH = :/bin:/usr/bin. 

HOME Name of the user’s login directory, set by login!\) from the password 
file passwdi 4). 

TERM The kind of terminal for which output is to be prepared. This informa- 
tion is used by commands, such as mm(l) or tplot! 1G), which may 
exploit special capabilities of that terminal. 

TZ Time zone information. The format is xxxnzzz where xxx is standard 
local time zone abbreviation, n is the difference in hours from GMT, 
and zzz is the abbreviation for the daylight-saving local time zone, if 
any; for example, EST5EDT. 

Further names may be placed in the environment by the export command and 
“name=value” arguments in sMl), or by exec( 2). It is unwise to conflict with 
certain shell variables that are frequently exported by .profile files: MAIL, PS1, 
PS2, IFS. 

SEE ALSO 

exec (2). 

env(l), login ( 1 ) , sh(l), nice(l), nohup(l), time(l) in the 3B2 Computer 5^5- 
tem User Reference Manual. 

tplot(lG) in the 3B2 Computer System Graphics Utilities Guide. 

mm(l) in the UNIX System V DOCUM ENTER’S WORKBENCH Software 

Introduction and Reference Manual. 
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NAME 

fcntl — file control options 

SYNOPSIS 

#include <fcntl.h> 

DESCRIPTION 

The fcntl (2) function provides for control over open files. This include file 
describes requests and arguments to fcntl and open (2). 

/* Flag values accessible to open (2) and fcntl(2) */ 

/* (The first three can only be set by open) */ 

#define O RDONLY 0 
#define 0_WRONLY 1 
#define 0_RDWR 2 

#define ONDELAY 04 /» Non-blocking I/O »/ 

#define OAPPEND 010 /* append (writes guaranteed at the end) */ 

#define OSYNC 020 /» synchronous write option */ 


/• Flag values accessible only to open (2) »/ 


#define O CREAT 00400 

#define OJTRUNC 01000 

#define O EXCL 02000 


/* open with file create (uses third open arg)»/ 
/* open with truncation */ 

/* exclusive open »/ 


/* fcntl (2) requests */ 
#define F DUPFD 0 
#define F GETFD 1 
#define F_SETFD 2 
#define F GETFL 3 
#define F SETFL 4 
#define F GETLK 5 
#define F SETLK 6 
#define F SETLKW 7 


/* Duplicate fildes »/ 

/» Get fildes flags */ 

/* Set fildes flags */ 

/* Get file flags */ 

/* Set file flags */ 

/* Get blocking file locks */ 

/» Set or clear file locks and fail on busy »/ 
/* Set or clear file locks and wait on busy */ 


/» file segment locking control structure */ 
struct flock { 

short l_type; 
short l_whence; 
long 1 start; 

long l ien; /» if 0 then until EOF »/ 

int l_pid; /* returned with F GETLK »/ 


/* file segment locking types «/ 

#define F RDLCK 01 /* Read lock »/ 

#define F WRLCK 02 /» Write lock »/ 

#define F UNLCK 03 /* Remove locks */ 

SEE ALSO 

fcntl (2), open (2). 
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NAME 

math — math functions and constants 

SYNOPSIS 

#include <math.h> 


DESCRIPTION 

This file contains declarations of all the functions in the Math Library 
(described in Section 3M), as well as various functions in the C Library (Sec- 
tion 3C) that return floating-point values. 

It defines the structure and constants used by the matherrOM ) error-handling 
mechanisms, including the following constant used as an error-return value: 

HUGE The maximum value of a single-precision floating-point 

number. 


The following mathematical constants are defined for user convenience: 


ME 

MLOG2E 
MLOGIOE 
MLN2 
MLN10 
M PI 


MSQRT2 

MSQRT12 


The base of natural logarithms (e). 

The base-2 logarithm of e. 

The base- 10 logarithm of e. 

The natural logarithm of 2. 

The natural logarithm of 10. 

rr, the ratio of the circumference of a circle to its diame- 
ter. (There are also several fractions of ir, its reciprocal, 
and its square root.) 

The positive square root of 2. 

The positive square root of 1/2. 


For the definitions of various machine-dependent “constants,” see the descrip- 
tion of the <values.h> header file. 


FILES 

/usr/include/math.h 


SEE ALSO 

intro(3), matherr(3M), values(5). 
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NAME 

prof — profile within a function 

SYNOPSIS 

#define MARK 
#include <prof.h> 

void MARK (name) 

DESCRIPTION 

MARK will introduce a mark called name that will be treated the same as a 
function entry point. Execution of the mark will add to a counter for that mark, 
and program-counter time spent will be accounted to the immediately preced- 
ing mark or to the function if there are no preceding marks within the active 
function. 

Name may be any combination of up to six letters, numbers or underscores. 
Each name in a single compilation must be unique, but may be the same as 
any ordinary program symbol. 

For marks to be effective, the symbol MARK must be defined before the header 
file <prof.h> is included. This may be defined by a preprocessor directive as 
in the synopsis, or by a command line argument, i.e: 

cc — p — DMARK foo.c 

If MARK is not defined, the MARKln&mt ) statements may be left in the source 
files containing them and will be ignored. 

EXAMPLE 

In this example, marks can be used to determine how much time is spent in 
each loop. Unless this example is compiled with MARK defined on the com- 
mand line, the marks are ignored. 

#include <prof.h> 

foo( ) 

( 

int i, j; 


MARK(loopl); 

for (i = 0; i < 2000; i++) { 

} 

MARK(loop2); 

for (j = 0; j < 2000; j++) ( 



SEE ALSO 

profil(2), monitor(3C). 

prof(l) in the 3B2 Computer System Extended Software Generation System 
Utilities. 
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NAME 

regexp - regular expression compile and match routines 
SYNOPSIS 

#define INIT < declarations > 

#define GETCO <getc code> 

#define PEEKCO <peekc code> 

#define UNGETC(c) Cungetc code> 

#define RETURN(pointer) < return code> 

#define ERROR(val) <error code> 

#include <regexp.h> 

char *compile (instring, expbuf, endbuf, eof) 
char *instring, »expbuf, *endbuf; 
int eof; 

int step (string, expbuf) 
char »string, *expbuf; 

extern char *Iocl, *loc2, *locs; 
extern int circf, sed, nbra; 

DESCRIPTION 

This page describes general-purpose regular expression matching routines in the 
form of ed{ 1), defined in /usr/include/regexp.h. Programs such as ed( 1), 
^erf(l), grepi 1), bs (1), expr(l), etc., which perform regular expression match- 
ing use this source file. In this way, only this file need be changed to maintain 
regular expression compatibility. 

The interface to this file is unpleasantly complex. Programs that include this 
file must have the following five macros declared before the 
“#include <regexp.h>” statement. These macros are used by the compile 
routine. 


GETCO 

PEEKCO 


UNGETC(c) 


RETURN ( pointer ) 


ERROR (val) 


Return the value of the next character in the regular 
expression pattern. Successive calls to GETCO should 
return successive characters of the regular expression. 

Return the next character in the regular expression. 
Successive calls to PEEKCO should return the same 
character (which should also be the next character 
returned by GETCO). 

Cause the argument c to be returned by the next call to 
GETCO (and PEEKCO). No more that one character 
of pushback is ever needed and this character is 
guaranteed to be the last character read by GETCO. 
The value of the macro UNGETC(c) is always ignored. 

This macro is used on normal exit of the compile rou- 
tine. The value of the argument pointer is a pointer to 
the character after the last character of the compiled 
regular expression. This is useful to programs which 
have memory allocation to manage. 

This is the abnormal return from t. j compile routine. 
The argument val is an error number (see table below 
for meanings). This call should never return. 
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ERROR 

MEANING 


11 

Range endpoint too large. 


16 

Bad number. 


25 

“\digit” out of range. 


36 

Illegal or missing delimiter. 


41 

No remembered search string. 


42 

\( \) imbalance. 


43 

Too many \(. 


44 

More than 2 numbers given in 

\{\). 

45 

} expected after \. 


46 

First number exceeds second in \{ \) 

49 

[ 1 imbalance. 


50 

Regular expression overflow. 



The syntax of the compile routine is as follows: 
compile (instring, expbuf, endbuf, eof) 

The first parameter instring is never used explicitly by the compile routine but 
is useful for programs that pass down different pointers to input characters. It 
is sometimes used in the INIT declaration (see below). Programs which call 
functions to input characters or have characters in an external array can pass 
down a value of ((char *) 0) for this parameter. 

The next parameter expbuf is a character pointer. It points to the place where 
the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where the compiled 
regular expression may be placed. If the compiled expression cannot fit in 
{endbuf— expbuf) bytes, a call to ERROR (50) is made. 

The parameter eof is the character which marks the end of the regular expres- 
sion. For example, in ed{ 1), this character is usually a /. 

Each program that includes this file must have a #define statement for INIT. 
This definition will be placed right after the declaration for the function com- 
pile and the opening curly brace ({). It is used for dependent declarations and 
initializations. Most often it is used to set a register variable to point the 
beginning of the regular expression so that this register variable can be used in 
the declarations for GETCO, PEEKCO and UNGETCO. Otherwise it can be 
used to declare external variables that might be used by GETCO, PEEKCO and 
UNGETCO. See the example below of the declarations taken from grepi 1). 

There are other functions in this file which perform actual regular expression 
matching, one of which is the function step. The call to step is as follows: 

step (string, expbuf) 

The first parameter to step is a pointer to a string of characters to be checked 
for a match. This string should be null terminated. 

The second parameter expbuf is the compiled regular expression which was 
obtained by a call of the function compile. 

The function step returns non-zero if the given string matches the regular 
expression, and zero if the expressions do not match. If there is a match, two 
external character pointers are set as a side effect to the call to step. The vari- 
able set in step is loci. This is a pointer to the first character that matched 
the regular expression. The variable loc2, which is set by the function advance, 
points to the character after the last character that matches the regular expres- 
sion. Thus if the regular expression matches the entire line, loci will point to 
the first character of string and loc2 will point to the null at the end of string. 
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Step uses the external variable circf which is set by compile if the regular 
expression begins with If this is set then step will try to match the regular 
expression to the beginning of the string only. If more than one regular expres- 
sion is to be compiled before the first is executed the value of circf should be 
saved for each compiled expression and circf should be set to that saved value 
before each call to step. 

The function advance is called from step with the same arguments as step. 
The purpose of step is to step through the string argument and call advance 
until advance returns non-zero indicating a match or until the end of string is 
reached. If one wants to constrain string to the beginning of the line in all 
cases, step need not be called; simply call advance. 

When advance encounters a * or \{ \} sequence in the regular expression, it 
will advance its pointer to the string to be matched as far as possible and will 
recursively call itself trying to match the rest of the string to the rest of the 
regular expression. As long as there is no match, advance will back up along 
the string until it finds a match or reaches the point in the string that initially 
matched the * or \{ \}. It is sometimes desirable to stop this backing up before 
the initial point in the string is reached. If the external character pointer Iocs 
is equal to the point in the string at sometime during the backing up process, 
advance will break out of the loop that backs up and will return zero. This is 
used by ed(,\) and sed(l) for substitutions done globally (not just the first 
occurrence, but the whole line) so, for example, expressions like s/y*//g do not 
loop forever. 


The additional external variables sed and nbra are used for special purposes. 
EXAMPLES 

The following is an example of how the regular expression macros and calls 
look from grep ( 1 ) : 


#define INIT 
#define GETCO 
#define PEEKCO 
#define UNGETC(c) 
#define RETURN (c) 
#define ERROR(c) 

#include < regexp. h> 


register char *sp = instring; 
(*sp++) 

(*sp) 

( sp) 

return; 

regerrO 


(void) compile (*argv, expbuf, &expbuf[ESIZE], \0'); 


if (stepOinebuf, expbuf)) 

succeed ( ) ; 

FILES 

/ usr/include/ regexp, h 
SEE ALSO 

ed(l), expr(l), grep(l), sed(l) in the 3B2 Computer System User Reference 
Manual. 

BUGS 

The handling of circf is kludgy. 

The actual code is probably easier to understand than this manual page. 
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NAME 

stat — data returned by stat system call 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

DESCRIPTION 

The system calls stat and fstat return data whose structure is defined by this 
include file. The encoding of the field stjnode is defined in this file also. 

/* 

* Structure of the result of stat 
*1 

struct stat 

{ 

devj stdev; 

ino_t stino; 

ushort stjnode; 

short stnlink; 

ushort st_uid; 

ushort st_gid; 

dev t st rdev; 

off t stsize; 

time t st_atime; 

timej stmtime; 
time t st ctime; 

}; 

#define S IFMT 0170000 /* type of file »/ 

#define S IFDIR 0040000 /* directory */ 

#define S IFCHR 0020000 /* character special */ 

#define SIFBLK 0060000 /» block special */ 

#define S IFREG 0100000 /* regular */ 

#define SJFIFO 0010000 /* fifo »/ 

#define S ISU1D 04000 /* set user id on execution */ 

#define S ISGID 02000 /* set group id on execution »/ 

#define S ISVTX 01000 /* save swapped text even after use */ 

#define S I READ 00400 /* read permission, owner */ 

#define SJWRITE 00200 /* write permission, owner */ 

#define S IEXEC 00100 /* execute/search permission, owner »/ 

FILES 

/usr/include/sys/ types. h 
/usr/include/sys/stat.h 

SEE ALSO 

stat (2), types(5). 
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NAME 

term — conventional names for terminals 


DESCRIPTION 

These names are used by certain commands (e.g., tabs{ 1) is maintained as part 
of the shell environment (see sMl), profiled), and environ^ 5)) in the variable 
$TERM: 


1520 
1620 
1620-12 
2621 
2631 
263 1-c 
263 1-e 
2640 
2645 
300 

300-12 

300s 

382 

300s- 12 
3045 
33 
37 

40-2 

40-4 

4540 

3270 

4000a 

4014 

43 

450 

450-12 

735 

745 

dumb 


sync 

hp 

lp 

tnl200 

tn300 


Datamedia 1520 

DIABLO 1620 and others using the HyType II printer 
same, in 12-pitch mode 
Hewlett-Packard 2621 series 
Hewlett-Packard 2631 line printer 
Hewlett-Packard 2631 line printer - compressed mode 
Hewlett-Packard 2631 line printer - expanded mode 
Hewlett-Packard 2640 series 

Hewlett-Packard 264n series (other than the 2640 series) 
DAS1/DTC/GSI 300 and others using the HyType I printer 
same, in 12-pitch mode 
DASI/DTC/GSI 300s 
DTC 382 

same, in 12-pitch mode 

Datamedia 3045 

TELETYPE® Model 33 KSR 

TELETYPE Model 37 KSR 

TELETYPE Model 40/2 

TELETYPE Model 40/4 

TELETYPE Model 4540 

IBM Model 3270 

Trendata 4000a 

TEKTRONIX 4014 

TELETYPE Model 43 KSR 

DASI 450 (same as Diablo 1620) 

same, in 12-pitch mode 

Texas Instruments T1735 and TI725 

Texas Instruments TI745 

generic name for terminals that lack reverse 

line-feed and other special escape sequences 

generic name for synchronous TELETYPE 

4540-compatible terminals 

Hewlett-Packard (same as 2645) 

generic name for a line printer 

User Electric TermiNet 1200 

User Electric TermiNet 300 


Up to 8 characters, chosen from [ a zO 9], make up a basic terminal name. 
Terminal sub-models and operational modes are distinguished by suffixes begin- 
ning with a — . Names should generally be based on original vendors, rather 
than local distributors. A terminal acquired from one vendor should not have 
more than one distinct basic name. 


Commands whose behavior depends on the type of terminal should accept argu- 
ments of the form -T term where term is one of the names given above; if no 
such argument is present, such commands should obtain the terminal type from 
the environment variable STERM, which, in turn, should contain term. 
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SEE ALSO 

profile(4), environ (5). 

sh(l), stty(l), tabs(l) in the 3B2 Computer System User Reference Manual. 
mm(l), nroff(l) in the UNIX System V DOCUMENTER’S WORKBENCH 
Software Introduction and Reference Manual. 
tplot(lG) in the 3B2 Computer System Graphics Utilities Guide. 

BUGS 

This is a small candle trying to illuminate a large, dark problem. Programs 
that ought to adhere to this nomenclature do so somewhat fitfully. 
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NAME 

types — primitive system data types 
SYNOPSIS 

#include <sys/types.h> 


DESCRIPTION 

The data types defined in the include file are used in UNIX system code; some 
data of these types are accessible to user code: 


typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 

typedef 


struct { int r[ 1 ]; } » 

long 

daddrt; 

char * 

caddr_t; 

unsigned int 

uint; 

unsigned short 

ushort; 

ushort 

ino_t; 

short 

cnt_t; 

long 

time_t; 

int 

labelttlO]; 

short 

dev_t; 

long 

offt; 

long 

paddrt; 

long 

key_t; 


physadr; 


The form daddrj is used for disk addresses except in an i-node on disk, see 
/s(4). Times are encoded in seconds since 00:00:00 GMT, January 1, 1970. 
The major and minor parts of a device code specify kind and unit number of a 
device and are installation-dependent. Offsets are measured in bytes from the 
beginning of a file. The label J variables are used to save the processor state 
while another process is running. 


SEE ALSO 

fs (4) . 
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NAME 

values — machine-dependent values 

SYNOPSIS 

#inciude <values.h> 

DESCRIPTION 

This file contains a set of manifest constants, conditionally defined for particu- 
lar processor architectures. 

The model assumed for integers is binary representation (one’s or two’s comple- 
ment), where the sign is represented by the value of the high-order bit. 

BITS(/>>p<?) The number of bits in a specified type (e.g., int). 

HIBITS The value of a short integer with only the high-order bit 

set (in most implementations, 0x8000). 

H1B1TL The value of a long integer with only the high-order bit 

set (in most implementations, 0x80000000). 

HIBITI The value of a regular integer with only the high-order 

bit set (usually the same as HIBITS or HIBITL). 

MAXSHORT The maximum value of a signed short integer (in most 

implementations, 0x7FFF = 32767). 

MAXLONG The maximum value of a signed long integer (in most 

implementations, 0x7FFFFFFF = 2147483647). 

MAXINT The maximum value of a signed regular integer (usually 

the same as MAXSHORT or MAXLONG). 

MAXFLOAT, LN MAXFLOAT The maximum value of a single-precision 

floating-point number, and its natural loga- 
rithm. 

MAXDOUBLE, LN MAXDOUBLE The maximum value of a double-precision 

floating-point number, and its natural loga- 
rithm. 

MINFLOAT, LN MINFLOAT The minimum positive value of a single- 
precision floating-point number, and its 
natural logarithm. 

MINDOUBLE, LN MINDOUBLE The minimum positive value of a double- 

precision floating-point number, and its 
natural logarithm. 

FSIGNIF The number of significant bits in the mantissa of a 

single-precision floating-point number. 

DSIGNIF The number of significant bits in the mantissa of a 

double-precision floating-point number. 

FILES 

/usr/include/values.h 

SEE ALSO 

intro(3), math(5). 
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NAME 

varargs — handle variable argument list 
SYNOPSIS 

#include <varargs.h> 

va_alist 

va_dcl 

void vastart(pvar) 
vajist pvar; 

type va_arg(pvar, type ) 
vajist pvar; 

void va_end(pvar) 
vajist pvar; 

DESCRIPTION 

This set of macros allows portable procedures that accept variable argument 
lists to be written. Routines that have variable argument lists (such as 
printfi 3S)) but do not use varargs are inherently nonportable, as different 
machines use different argument-passing conventions. 

vaalist is used as the parameter list in a function header, 
vadcl is a declaration for va alist. No semicolon should follow vadcl. 
vajist is a type defined for the variable used to traverse the list. 
va_start is called to initialize pvar to the beginning of the list. 

va arg will return the next argument in the list pointed to by pvar. Type is the 
type the argument is expected to be. Different types can be mixed, but it is up 
to the routine to know what type of argument is expected, as it cannot be 
determined at runtime. 

vaend is used to clean up. 

Multiple traversals, each bracketed by vajtart ... va end, are possible. 
EXAMPLE 

This example is a possible implementation of execKl). 

#include <varargs.h> 

#define MAXARGS 100 

/* execl is called by 

execKfile, argl, arg2 (char *)0); 

»/ 

execl (va_alist) 
vadcl 
( 

vajist ap; 
char ‘file; 

char »args[MAXARGS]; 
int argno = 0; 

vastart(ap); 

file = va_arg(ap, char *); 

while ((args[argno-Hj = va_arg(ap, char *)) != (char *)0) 

vaend(ap); 

return execv(file, args); 

} 
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SEE ALSO 

exec(2), printf(3S). 

BUGS 

It is up to the calling routine to specify how many arguments there are, since it 
is not always possible to determine this from the stack frame. For example, 
execl is passed a zero pointer to signal the end of the list. Print f can tell how 
many arguments are there by the format. 

It is non-portable to specify a second argument of char, short, or float to 
va arg, since arguments seen by the called function are not char, short, or 
float. C converts char and short arguments to int and converts float arguments 
to double before passing them to a function. 
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